skalpel 3.0.9 → 3.0.11

package/INSTALL.md

@@ -47,7 +47,7 @@ The first-run flow assumes the user has obtained an `sk-skalpel-*` API key on We
 
 This flow corresponds to Journey 1 — First launch, fresh authentication — in `SPEC.md`. That narrative describes what the user feels at each step; this document describes what the install machinery actually does.
 
-If the user runs `skalpel` without first obtaining an API key, the TUI exits per spec §8.4 with a stderr pointer at `skalpel login`. The wizard above is the path for users who arrived through the post-signup install hub on Web; users with broken or missing auth state are returned to the shell.
+If the user runs `skalpel` without first obtaining an API key, the TUI exits per spec §8.4 with a stderr pointer at `skalpel login`. The wizard above is the path for users who arrived through the post-signup install hub on Web; users with broken or missing auth state are returned to the shell. To sign out of an existing account on this machine, run `skalpel logout` from a shell — the CLI revokes the backend session (best-effort) and removes `auth.json` via `internal/auth.Delete`.
 
 An alternative first-run flow uses `skalpel login` from the shell directly. That command runs a device-code flow against Cognito (per the Auth handoff section of the cross-surface contract) and writes `auth.json` without the user having to paste an API key. The two flows produce equivalent on-disk state; the API-key-paste flow is the one a user lands in when arriving from the Web post-signup install hub, and the device-code flow is the one a user runs when reauthenticating an account that has already been signed in on this machine before.
 
@@ -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/README.md

@@ -18,6 +18,16 @@ npm install -g skalpel
 
 Both `skalpel` and `skalpeld` are placed on your `PATH`. For details on what gets installed where, per-OS service registration, updates, and uninstall, see [INSTALL.md](./INSTALL.md).
 
+## Subcommands
+
+`skalpel` accepts a small set of subcommands:
+
+- `skalpel` — launch the Bubble Tea TUI (default).
+- `skalpel login` — browser-loopback sign-in; writes `auth.json`.
+- `skalpel logout` — revoke the active session (best-effort) and delete `auth.json`; supports `--yes` to skip the `[y/N]` confirm.
+- `skalpel uninstall` — clean up skalpel state on this machine.
+- `skalpel --version` / `skalpel --help` — utilities.
+
 ## Links
 
 - Homepage: https://skalpel.ai

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;
   }
@@ -316,11 +322,90 @@ function runUninstall(rest) {
     );
   }
 
-  process.stdout.write(`${dim('To finish removal, also run:')}\n`);
-  process.stdout.write(`  npm uninstall -g skalpel\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.9",
+  "version": "3.0.11",
   "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.9",
-    "@skalpelai/skalpel-darwin-x64": "3.0.9",
-    "@skalpelai/skalpel-linux-arm64": "3.0.9",
-    "@skalpelai/skalpel-linux-x64": "3.0.9",
-    "@skalpelai/skalpel-win32-x64": "3.0.9"
+    "@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"
   }
 }