skalpel 3.0.8 → 3.0.10

package/INSTALL.md

@@ -71,11 +71,26 @@ A user who has rolled back to a previous version (by running `npm install -g ska
 
 ## Uninstall
 
-`skalpel uninstall` is the one-liner for a clean removal. It unregisters the per-OS service entry (launchd / systemd user / Task Scheduler), removes the managed shell-rc block, and deletes `auth.json`, `config.toml`, `skalpeld.lock`, and `logs/` from the per-OS configuration directory. To preserve user data (engine toggles, active org, cached auth), pass `--keep-data`. `--dry-run` previews every action without writing anything. The command does not remove the npm package itself; after running `skalpel uninstall`, finish with `npm uninstall -g skalpel`.
+```
+npx skalpel uninstall
+```
 
-`npm uninstall -g skalpel` on its own removes both binaries. There is no separate uninstall command for `skalpeld`; the package is the unit of removal. Before npm removes the binaries it fires the package's `preuninstall` hook, which invokes `node postinstall/index.js --uninstall`; that pass removes the rc-file managed-block injected on install (so the user's shell stops pointing at the now-defunct local proxy port) and unregisters the per-OS service entry (so `launchctl`, `systemctl --user`, or `schtasks` stops trying to start a daemon whose binary is about to vanish). The shim and registration cleanup happen before the binaries themselves are removed; an interrupted uninstall leaves a coherent intermediate state. The `preuninstall` hook deliberately preserves user data on disk so that `npm uninstall -g skalpel` followed by `npm install -g skalpel` is a non-destructive reinstall; the `skalpel uninstall` one-liner above is the path for users who want a full wipe.
+is the canonical one-liner for a clean, full removal on every supported OS. It works whether or not skalpel was previously installed globally:
 
-`npx skalpel` users have no global install to uninstall; the npx cache is cleaned by npm on its own schedule. For an `npx`-only user who wants to clean up shell rc-file and service registration without waiting on cache eviction, `skalpel uninstall` performs the same cleanup the `preuninstall` hook would, plus the user-data wipe.
+1. Unregisters the per-OS service entry (launchd on macOS, systemd user unit on Linux, Task Scheduler entry on Windows).
+2. Removes the managed shell-rc block injected on install.
+3. Deletes user state under the per-OS configuration directory: `auth.json`, `config.toml`, `skalpeld.lock`, `logs/`, and `cache/`.
+4. Auto-detects a global npm install (via `npm prefix -g`) and removes it via `npm uninstall -g skalpel`, so the `skalpel` binary leaves your `PATH` in the same command.
+
+Flags: `--keep-data` preserves user-data files (engine toggles, cached auth) for a future reinstall; `--keep-package` preserves the global npm package (only the state cleanup runs); `--dry-run` previews every action without writing anything.
+
+`skalpel uninstall` from a global install behaves identically — same flags, same auto-removal of the npm package. Pick whichever is convenient: `npx skalpel uninstall` requires no prior install; `skalpel uninstall` is faster on a machine that already has the binary on `PATH`.
+
+### Why `npm uninstall -g skalpel` is not the documented path
+
+npm 7+ removed the `preuninstall`/`uninstall`/`postuninstall` lifecycle scripts; the `npm uninstall` command runs Arborist's `reify` which simply deletes files from the global `node_modules` and returns. There is no hook left for skalpel to clean up the rc-file managed block, the service entry, or user data on `npm uninstall -g skalpel` alone. Running `npm uninstall -g skalpel` without first running `skalpel uninstall` (or `npx skalpel uninstall`) leaves orphaned shell-rc env vars pointing at a dead proxy port and an orphaned launchd/systemd/Task Scheduler entry trying to start a binary that no longer exists. The `npx skalpel uninstall` one-liner above does both the state cleanup and the package removal in a single command — that's why it's the documented path.
+
+The configuration directory itself (auth.json + config.toml + cache + logs) is deliberately wiped by the default uninstall so a reinstalled skalpel starts from a known state. Users who want to reinstall and keep their auth + engine toggles should pass `--keep-data`.
 
 ## Version coupling
 

package/npm-bin/skalpel.js

@@ -189,6 +189,7 @@ function resolveBinary(name, argv) {
 // only place this command can live.
 function runUninstall(rest) {
   let cleanupData = true;
+  let removePackage = true;
   let dryRun = false;
   let showHelp = false;
   for (const a of rest) {
@@ -196,6 +197,9 @@ function runUninstall(rest) {
       case '--keep-data':
         cleanupData = false;
         break;
+      case '--keep-package':
+        removePackage = false;
+        break;
       case '--dry-run':
         dryRun = true;
         break;
@@ -212,14 +216,16 @@ function runUninstall(rest) {
     const head = colored ? theme.bold(theme.lilac('skalpel uninstall')) : 'skalpel uninstall';
     const dim = colored ? theme.dim : (s) => s;
     process.stdout.write(
-      `${head} — clean up skalpel state on this machine\n\n` +
-      `usage: skalpel uninstall [--keep-data] [--dry-run]\n\n` +
+      `${head} — fully remove skalpel from this machine\n\n` +
+      `usage: skalpel uninstall [--keep-data] [--keep-package] [--dry-run]\n\n` +
       `By default, removes:\n` +
       `  • per-OS service entry (launchd / systemd user / Task Scheduler)\n` +
       `  • managed shell-rc block injected on install\n` +
-      `  • auth.json, config.toml, skalpeld.lock, and logs/ (use --keep-data to preserve)\n\n` +
-      `${dim('Does not remove the npm package itself. To finish removal, run:')}\n` +
-      `  npm uninstall -g skalpel\n`
+      `  • auth.json, config.toml, skalpeld.lock, logs/ and cache/ (use --keep-data to preserve)\n` +
+      `  • the global npm package itself (use --keep-package to preserve the binary)\n\n` +
+      `${dim('Equivalent invocations (both do the same thing):')}\n` +
+      `  skalpel uninstall          ${dim('(from a global install)')}\n` +
+      `  npx skalpel uninstall      ${dim('(no global install needed)')}\n`
     );
     return 0;
   }
@@ -298,11 +304,108 @@ function runUninstall(rest) {
     // Fallback to the old unconditional message if no summary made it back.
     process.stdout.write(`\n${ok} skalpel state removed from this machine.\n`);
   }
-  process.stdout.write(`${dim('To finish removal, also run:')}\n`);
-  process.stdout.write(`  npm uninstall -g skalpel\n`);
+
+  // Only emit the "running agents still have stale env" hint when
+  // something was actually removed (or in dry-run); on already-clean
+  // re-runs the hint adds noise without value.
+  const ranAnyCleanup = summary && !(
+    summary.rcBlocksRemoved === 0 &&
+    !summary.serviceFileRemoved &&
+    summary.userDataFilesRemoved === 0
+  );
+  if (!summary || ranAnyCleanup) {
+    process.stdout.write(
+      `${dim('Note: any open shells or running coding agents (Claude Code, Codex, ' +
+      'Cursor, etc.) still have the skalpel proxy env vars cached in their ' +
+      'environment. Open a fresh shell and restart any active agents to drop ' +
+      'them.')}\n`
+    );
+  }
+
+  // True-uninstall: auto-detect a global npm install of `skalpel` and
+  // remove it via `npm uninstall -g skalpel`. This makes
+  // `npx skalpel uninstall` (or `skalpel uninstall` from a global
+  // install) a single one-stop true uninstall on every OS.
+  //
+  // Safety notes:
+  //   - When invoked from a global install (not via npx), we're about
+  //     to delete the files Node loaded our shim from. Node read the
+  //     script and closed the handle, so deletion is safe cross-OS.
+  //   - When invoked from npx, the global install (if any) is at a
+  //     different prefix than the npx cache, so no self-deletion.
+  //   - We skip when --keep-package is passed or when the postinstall
+  //     summary indicates nothing was removed and no global install
+  //     exists (i.e. user has nothing to uninstall).
+  let globalRemoved = false;
+  if (removePackage && !dryRun) {
+    const detected = detectGlobalInstall();
+    if (detected) {
+      const r = removeGlobalInstall();
+      if (r.removed) {
+        globalRemoved = true;
+        process.stdout.write(`${ok} Removed global npm package skalpel (${detected.pkgRoot}).\n`);
+      } else {
+        process.stdout.write(
+          `\n${dim('Could not auto-remove the global skalpel package ')}` +
+          `${dim('(' + r.reason + ').')}\n` +
+          `Run manually:\n  npm uninstall -g skalpel\n` +
+          dim('  (sudo may be required on some setups)\n')
+        );
+      }
+    }
+  } else if (removePackage && dryRun) {
+    const detected = detectGlobalInstall();
+    if (detected) {
+      process.stdout.write(`${dim('[dry-run] would run: npm uninstall -g skalpel')}\n`);
+      process.stdout.write(`${dim('  (' + detected.pkgRoot + ')')}\n`);
+    }
+  }
+
+  if (globalRemoved || (summary && (summary.rcBlocksRemoved || summary.serviceFileRemoved || summary.userDataFilesRemoved))) {
+    process.stdout.write(`\n${ok} skalpel fully removed from this machine.\n`);
+  }
   return 0;
 }
 
+// detectGlobalInstall returns { prefix, pkgRoot } if a global npm
+// install of `skalpel` exists, or null. Uses `npm prefix -g` which is
+// the cross-OS canonical way to find the global root. We don't trust
+// `which skalpel` because PATH ordering can hide a global install
+// behind another shim.
+function detectGlobalInstall() {
+  const r = spawnSync('npm', ['prefix', '-g'], {
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+  });
+  if (r.status !== 0 || !r.stdout) return null;
+  const prefix = r.stdout.trim();
+  if (!prefix) return null;
+  // On Unix, `npm prefix -g` returns e.g. /usr/local; the package is
+  // at lib/node_modules/skalpel. On Windows, prefix is the AppData
+  // dir itself; package is at node_modules/skalpel.
+  const candidate = process.platform === 'win32'
+    ? path.join(prefix, 'node_modules', 'skalpel')
+    : path.join(prefix, 'lib', 'node_modules', 'skalpel');
+  // Avoid false positive when we ARE the global install we just
+  // checked (npx cache lives elsewhere, so this is fine; only matters
+  // if some non-npx, non-global path resolves to the same dir).
+  if (!fs.existsSync(candidate)) return null;
+  return { prefix, pkgRoot: candidate };
+}
+
+// removeGlobalInstall shells out to `npm uninstall -g skalpel`. Uses
+// shell: true on Windows so the .cmd shim resolves; harmless on
+// Unix. Returns { removed: bool, reason: string }.
+function removeGlobalInstall() {
+  const r = spawnSync('npm', ['uninstall', '-g', 'skalpel'], {
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  });
+  if (r.error) return { removed: false, reason: r.error.message };
+  if (r.status !== 0) return { removed: false, reason: `npm exited ${r.status}` };
+  return { removed: true };
+}
+
 if (require.main === module) {
   const argv = process.argv.slice(2);
   if (argv[0] === 'uninstall') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "3.0.8",
+  "version": "3.0.10",
   "description": "Skalpel — local proxy and TUI for coding agents (skalpel + skalpeld bundle).",
   "license": "Apache-2.0",
   "homepage": "https://skalpel.ai",
@@ -29,7 +29,6 @@
   },
   "scripts": {
     "postinstall": "node postinstall/index.js",
-    "preuninstall": "node postinstall/index.js --uninstall",
     "test": "echo 'no top-level tests; run make test or npm run test:rc-edit' && exit 0",
     "test:rc-edit": "node postinstall/lib/rc-edit.test.js"
   },
@@ -54,10 +53,10 @@
     "x64"
   ],
   "optionalDependencies": {
-    "@skalpelai/skalpel-darwin-arm64": "3.0.8",
-    "@skalpelai/skalpel-darwin-x64": "3.0.8",
-    "@skalpelai/skalpel-linux-arm64": "3.0.8",
-    "@skalpelai/skalpel-linux-x64": "3.0.8",
-    "@skalpelai/skalpel-win32-x64": "3.0.8"
+    "@skalpelai/skalpel-darwin-arm64": "3.0.10",
+    "@skalpelai/skalpel-darwin-x64": "3.0.10",
+    "@skalpelai/skalpel-linux-arm64": "3.0.10",
+    "@skalpelai/skalpel-linux-x64": "3.0.10",
+    "@skalpelai/skalpel-win32-x64": "3.0.10"
   }
 }

package/postinstall/index.js

@@ -226,12 +226,35 @@ function main(argv) {
     return 0;
   }
 
-  // B32: refuse to run under `npx skalpel`.
-  if (paths.isNpxInvocation()) {
-    process.stderr.write(
-      'Skalpel does not support `npx skalpel` — please run `npm i -g @skalpelai/skalpel` instead.\n'
+  // npx mode: prior to v3.0.9 we returned exit 1 here, which caused
+  // npm to roll back the cached package install — leaving an empty
+  // ~/.npm/_npx/<hash>/ dir and a silent failure that re-prompted on
+  // every subsequent `npx skalpel` call. The original reason for the
+  // gate (B32) was that paths.binPath() couldn't locate the platform
+  // binary under npx's directory layout. That was fixed in v3.0.1
+  // when binPath was rewritten to use require.resolve against the
+  // platform sub-package (see paths.js:99-116) — which works under
+  // npx, global, or local install paths uniformly.
+  //
+  // We still skip the install wizard under npx because the wizard's
+  // service-register step would bake the npx cache path
+  // (~/.npm/_npx/<hash>/...) into the OS service unit, and that path
+  // is evicted by npx's cache GC. Exit 0 instead of 1 so npm install
+  // completes and the binary becomes invokable.
+  //
+  // Uninstall, however, MUST run under npx: a user running
+  // `npx skalpel uninstall` to clean up a prior `npm install -g`
+  // would otherwise hit the same skip and have nothing happen.
+  if (paths.isNpxInvocation() && !opts.uninstall) {
+    log.info(
+      'npx mode detected — skipping install wizard (service-register / ' +
+      'env-inject would bake transient npx cache paths into your system).'
     );
-    return 1;
+    log.info(
+      'For a persistent install with daemon-on-boot and shell env vars, ' +
+      'run: `npm install -g skalpel`'
+    );
+    return 0;
   }
 
   const total = 5;