Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(uninstall): look for the desktop's data under node-terminal, not nodeterm

reviewa11fdcbc583a
diff --git a/CLAUDE.md b/CLAUDE.md
index 7a11ead8b..c543e3bf6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6312,6 +6312,17 @@ the same script hand-packs `build/icon.icns` (size-checked frames — issue #369
zip, `--publish never`). Production release signing/notarization and the update-feed hosting are
handled outside this repo.
+**The running app's name is `node-terminal`, not `nodeterm`.** Electron reads `app.name` from
+package.json's top-level `name`; `productName` lives only under `build`, which electron-builder
+strips from the packaged package.json, so it names the bundle and the installer and nothing else.
+Everything keyed by the app NAME therefore says `node-terminal` on every build, dev or installed:
+`userData` (`~/Library/Application Support/node-terminal`, `~/.config/node-terminal`,
+`%APPDATA%\node-terminal`), the `node-terminal Safe Storage` Keychain entry, electron-updater's
+`node-terminal-updater` cache. Only what is keyed by the bundle id (`com.nodeterm.app`) or the
+bundle itself (`/Applications/nodeterm.app`) carries `nodeterm`. `scripts/uninstall.sh` looked
+under `…/nodeterm` and never found the desktop's data; `scripts/uninstall.test.ts` now ties its
+`APP_NAME` to package.json `name`.
+
**Linux ships AppImage + deb + rpm**, all unsigned, all built by `release-linux` on a plain
`ubuntu-latest` runner (`npm run dist:linux` locally). Three things about it are easy to get wrong:
diff --git a/docs/uninstall.md b/docs/uninstall.md
index 9cd3f0555..ff58e2cdc 100644
--- a/docs/uninstall.md
+++ b/docs/uninstall.md
@@ -21,13 +21,24 @@ to apply. Interactive runs (downloaded script, no pipe) confirm before touching
| Location | What it holds | Written by |
| --- | --- | --- |
-| `~/Library/Application Support/nodeterm` (macOS) / `~/.config/nodeterm` (Linux) | The Electron user-data dir: `workspace.json`, `settings.json`, generated `tmux.conf`, `terminal-scrollback/`, `hook-endpoint.env`, `context-links/`, `canvas-control/`, `claude-accounts/<id>/` (managed-account config dirs), `speech-models/`, media caches, secret stores, `device-id`, browser storage | everything behind `CorePlatform.userDataDir` |
+| `~/Library/Application Support/node-terminal` (macOS) / `~/.config/node-terminal` (Linux) | The Electron user-data dir: `workspace.json`, `settings.json`, generated `tmux.conf`, `terminal-scrollback/`, `hook-endpoint.env`, `context-links/`, `canvas-control/`, `claude-accounts/<id>/` (managed-account config dirs), `speech-models/`, media caches, secret stores, `device-id`, browser storage | everything behind `CorePlatform.userDataDir` |
| `~/.nodeterm` | Machine-stable state shared by every instance: `agent-hooks/*.sh` (the managed hook scripts), `ssh-cm/*.sock` (SSH ControlMaster sockets), `acks/`, `pending/`, `push-grants/`, `cx/`, `codex-thread-names/`, the app-private ssh-agent | `install-helper.ts`, `control-master.ts`, `pairing-service.ts`, … |
-| `~/Library/Caches/nodeterm*`, `~/Library/Caches/com.nodeterm.app*`, `~/Library/Application Support/Caches/nodeterm-updater`, `~/Library/Preferences/com.nodeterm.app.plist`, `~/Library/Saved Application State/…`, `~/Library/HTTPStorages/com.nodeterm.app`, `~/Library/Logs/nodeterm` | Chromium/electron-updater caches, macOS window state | Electron / macOS |
-| Keychain entry `nodeterm Safe Storage` (macOS) | The key Electron `safeStorage` encrypts local secrets with | Electron |
+| `~/Library/Caches/node-terminal`, `~/Library/Caches/node-terminal-updater`, `~/Library/Caches/com.nodeterm.app*`, `~/Library/Preferences/com.nodeterm.app.plist`, `~/Library/Saved Application State/…`, `~/Library/HTTPStorages/com.nodeterm.app`, `~/Library/Logs/node-terminal` (macOS) / `~/.cache/node-terminal`, `~/.cache/node-terminal-updater` (Linux) | Chromium/electron-updater caches, macOS window state | Electron / macOS |
+| Keychain entry `node-terminal Safe Storage` (macOS) | The key Electron `safeStorage` encrypts local secrets with | Electron |
| `/Applications/nodeterm.app` (or the Homebrew cask) | The app itself | `install.sh` / brew |
| `~/.nodeterm-server-app`, `~/.nodeterm-server`, systemd units `nodeterm-server.service` + `nodeterm-server-update.{service,timer}` (system or `--user`) | Server Edition checkout, private Node runtime, data dir, service + daily auto-update timer | `install-server.sh` |
+**Why `node-terminal` and not `nodeterm`.** Everything Electron keys by the app's *name* — the
+user-data dir, the `Safe Storage` Keychain entry, electron-updater's `<name>-updater` cache —
+uses `app.name`, which Electron reads from the top-level `name` in package.json
+(`node-terminal`). `productName` (`nodeterm`) lives only under `build`, which electron-builder
+strips from the packaged package.json, so it names the bundle and the installer and never
+reaches the running app. Every desktop build, dev or installed, therefore writes to
+`…/node-terminal`. What is keyed by the bundle id (`com.nodeterm.app`: prefs, saved state,
+HTTPStorages, ShipIt) or by the bundle itself (`/Applications/nodeterm.app`) does carry the
+`nodeterm` spelling. `scripts/uninstall.test.ts` ties the script's `APP_NAME` to package.json
+`name`.
+
### 2. Integration merged into OTHER tools' config — reverted surgically
nodeterm integrates with agent CLIs you already have by merging entries into their config.
@@ -110,5 +121,5 @@ So the honest design is:
(inert in sessions nodeterm didn't spawn) and marker-reversible.
Windows note: the desktop build ships as an NSIS installer with its own uninstaller
-(Add/Remove Programs); after running it, delete `%APPDATA%\nodeterm` and
+(Add/Remove Programs); after running it, delete `%APPDATA%\node-terminal` and
`%USERPROFILE%\.nodeterm`. The POSIX script does not run there.
diff --git a/scripts/uninstall.sh b/scripts/uninstall.sh
index e6ad37b64..be562dc3e 100644
--- a/scripts/uninstall.sh
+++ b/scripts/uninstall.sh
@@ -36,7 +36,7 @@
# with a warning — they are harmless: the installed hook command is self-guarded and becomes
# a silent no-op once the script it points to is deleted.
# - macOS and Linux. On Windows use the NSIS uninstaller (Add/Remove Programs), then delete
-# %APPDATA%\nodeterm and %USERPROFILE%\.nodeterm.
+# %APPDATA%\node-terminal and %USERPROFILE%\.nodeterm.
set -u
DRY_RUN=0
@@ -60,10 +60,15 @@ note() { printf ' \033[2m%s\033[0m\n' "$1"; }
HOME="${HOME:-$(cd ~ && pwd)}"
# ---- locations (must mirror what the app writes; see docs/uninstall.md) ----------------------
+# Electron's app.name — and with it the user-data dir, the Keychain "Safe Storage" entry and
+# electron-updater's cache dir — is package.json's top-level `name`, NOT `build.productName`:
+# electron-builder strips `build` from the packaged package.json, so "nodeterm" only ever names
+# the bundle and the installer. Must equal package.json `name` (scripts/uninstall.test.ts).
+APP_NAME="node-terminal"
if [ "$OS" = "Darwin" ]; then
- USER_DATA="$HOME/Library/Application Support/nodeterm"
+ USER_DATA="$HOME/Library/Application Support/$APP_NAME"
else
- USER_DATA="${XDG_CONFIG_HOME:-$HOME/.config}/nodeterm"
+ USER_DATA="${XDG_CONFIG_HOME:-$HOME/.config}/$APP_NAME"
fi
NT_HOME="$HOME/.nodeterm" # agent-hooks, ssh-cm sockets, acks, push-grants…
SERVER_APP="${NODETERM_APP_DIR:-$HOME/.nodeterm-server-app}"
@@ -357,16 +362,17 @@ add_dir() { [ -e "$1" ] && { DIRS_TO_REMOVE+=("$1"); plan "Delete $1"; FOUND_ANY
add_dir "$NT_HOME"
add_dir "$USER_DATA"
if [ "$OS" = "Darwin" ]; then
- add_dir "$HOME/Library/Caches/nodeterm"
+ add_dir "$HOME/Library/Caches/$APP_NAME"
add_dir "$HOME/Library/Caches/com.nodeterm.app"
add_dir "$HOME/Library/Caches/com.nodeterm.app.ShipIt"
- add_dir "$HOME/Library/Application Support/Caches/nodeterm-updater"
+ add_dir "$HOME/Library/Caches/$APP_NAME-updater"
add_dir "$HOME/Library/Preferences/com.nodeterm.app.plist"
add_dir "$HOME/Library/Saved Application State/com.nodeterm.app.savedState"
add_dir "$HOME/Library/HTTPStorages/com.nodeterm.app"
- add_dir "$HOME/Library/Logs/nodeterm"
+ add_dir "$HOME/Library/Logs/$APP_NAME"
else
- add_dir "${XDG_CACHE_HOME:-$HOME/.cache}/nodeterm"
+ add_dir "${XDG_CACHE_HOME:-$HOME/.cache}/$APP_NAME"
+ add_dir "${XDG_CACHE_HOME:-$HOME/.cache}/$APP_NAME-updater"
fi
add_dir "$SERVER_APP"
add_dir "$SERVER_DATA"
@@ -379,8 +385,8 @@ if [ "$OS" = "Darwin" ]; then
elif [ -d "$APP_BUNDLE" ]; then
plan "Delete $APP_BUNDLE"; FOUND_ANY=1
fi
- if security find-generic-password -s "nodeterm Safe Storage" >/dev/null 2>&1; then
- plan "Delete the 'nodeterm Safe Storage' Keychain entry"; FOUND_ANY=1
+ if security find-generic-password -s "$APP_NAME Safe Storage" >/dev/null 2>&1; then
+ plan "Delete the '$APP_NAME Safe Storage' Keychain entry"; FOUND_ANY=1
fi
fi
@@ -506,7 +512,7 @@ if [ "$OS" = "Darwin" ]; then
rm -rf "$APP_BUNDLE" && ok "Deleted $APP_BUNDLE" \
|| warn "Could not delete $APP_BUNDLE — drag it to the Trash"
fi
- security delete-generic-password -s "nodeterm Safe Storage" >/dev/null 2>&1 || true
+ security delete-generic-password -s "$APP_NAME Safe Storage" >/dev/null 2>&1 || true
defaults delete com.nodeterm.app >/dev/null 2>&1 || true
fi
diff --git a/scripts/uninstall.test.ts b/scripts/uninstall.test.ts
new file mode 100644
index 000000000..f8ba66e18
--- /dev/null
+++ b/scripts/uninstall.test.ts
@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, chmodSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+// Electron's `app.name` — and with it the user-data dir, the Keychain "Safe Storage" entry and
+// electron-updater's cache dir — comes from package.json's top-level `name`. `build.productName`
+// ("nodeterm") names only the bundle and the installer: electron-builder strips `build` from the
+// packaged package.json, so it never reaches the running app. The uninstaller looked under
+// `…/nodeterm` and so never found the desktop's data. Deriving the expectation from package.json
+// (not a literal) is the point: a rename of `name` must move the uninstaller with it.
+const APP_NAME: string = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8')).name
+const SCRIPT = join(__dirname, 'uninstall.sh')
+
+let root: string
+let home: string
+let shims: string
+
+function shim(name: string, body: string): void {
+ const p = join(shims, name)
+ writeFileSync(p, `#!/bin/sh\n${body}\n`)
+ chmodSync(p, 0o755)
+}
+
+/** Plan-only run against a fixture HOME. Every tool that could reach the REAL machine (a running
+ * app, the tmux servers this box hosts nodeterm on, systemd, the Keychain, brew) is shimmed to
+ * answer "nothing here", and the env is built from scratch so no XDG_* / *_HOME leaks in. */
+function dryRun(): string {
+ return execFileSync('bash', [SCRIPT, '--dry-run'], {
+ encoding: 'utf8',
+ env: { HOME: home, PATH: `${shims}:${dirname(process.execPath)}:/usr/bin:/bin` },
+ stdio: ['ignore', 'pipe', 'pipe']
+ })
+}
+
+beforeEach(() => {
+ root = mkdtempSync(join(tmpdir(), 'nt-uninstall-'))
+ home = join(root, 'home')
+ shims = join(root, 'shims')
+ mkdirSync(home)
+ mkdirSync(shims)
+ for (const t of ['tmux', 'pgrep', 'systemctl', 'brew', 'security']) shim(t, 'exit 1')
+})
+
+afterEach(() => {
+ rmSync(root, { recursive: true, force: true })
+})
+
+// `uname` is shimmed too, so BOTH branches run on any POSIX runner — the macOS paths (Library,
+// Keychain) would otherwise only ever be exercised on a Mac.
+describe.skipIf(process.platform === 'win32').each([
+ {
+ os: 'Linux',
+ userData: () => join(home, '.config', APP_NAME),
+ updaterCache: () => join(home, '.cache', `${APP_NAME}-updater`)
+ },
+ {
+ os: 'Darwin',
+ userData: () => join(home, 'Library', 'Application Support', APP_NAME),
+ updaterCache: () => join(home, 'Library', 'Caches', `${APP_NAME}-updater`)
+ }
+])('uninstall.sh on $os finds what the desktop app writes', ({ os, userData, updaterCache }) => {
+ beforeEach(() => shim('uname', `echo ${os}`))
+
+ it('plans to delete the Electron user-data dir named after package.json `name`', () => {
+ mkdirSync(userData(), { recursive: true })
+ writeFileSync(join(userData(), 'settings.json'), '{}')
+
+ expect(dryRun()).toContain(`Delete ${userData()}`)
+ })
+
+ it('enumerates project .nodeterm folders from that dir’s workspace.json (kept, not deleted)', () => {
+ const project = join(root, 'repo')
+ mkdirSync(join(project, '.nodeterm'), { recursive: true })
+ mkdirSync(userData(), { recursive: true })
+ writeFileSync(
+ join(userData(), 'workspace.json'),
+ JSON.stringify({ version: 3, entries: [{ kind: 'local', cwd: project }] })
+ )
+
+ const out = dryRun()
+ expect(out).toContain('Would be KEPT')
+ expect(out).toContain(join(project, '.nodeterm'))
+ })
+
+ it('plans to delete the electron-updater cache (`<name>-updater`)', () => {
+ mkdirSync(updaterCache(), { recursive: true })
+
+ expect(dryRun()).toContain(`Delete ${updaterCache()}`)
+ })
+
+ it.runIf(os === 'Darwin')('looks up the Keychain entry Electron actually creates', () => {
+ shim('security', `[ "$3" = "${APP_NAME} Safe Storage" ] && exit 0; exit 1`)
+
+ expect(dryRun()).toContain(`Delete the '${APP_NAME} Safe Storage' Keychain entry`)
+ })
+})