@term-hub/term-hub 0.1.1 → 0.1.3

package/README.md

@@ -1,12 +1,32 @@
-# Terminal Hub
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/@term-hub/term-hub@latest/assets/icon.png" alt="Terminal Hub logo" width="120"></p>
 
-**Terminal mission control.** Capture every interactive shell you open (Terminal.app, iTerm, VS Code, tmux panes, …) and manage them all from one desktop app — plus spawn your own, independent of any terminal.
+<h1 align="center">Terminal Hub</h1>
+
+<p align="center"><b>Terminal mission control.</b> Capture every interactive shell you open (Terminal.app, iTerm, VS Code, tmux panes, …) and manage them all from one desktop app — plus spawn your own, independent of any terminal.</p>
+
+<p align="center">
+  <img alt="macOS" src="https://img.shields.io/badge/macOS-supported-brightgreen">
+  <img alt="Linux" src="https://img.shields.io/badge/Linux-supported-brightgreen">
+  <img alt="Windows" src="https://img.shields.io/badge/Windows-in%20progress-orange">
+</p>
 
 Capture is **opt-in, consent-gated, and fully reversible**. Nothing is captured until you say yes; one command reverts everything.
 
 > A terminal you kill from Terminal Hub really dies. A hub-owned session you spawn keeps running until you kill it. The background router can crash and **your shells survive** — there's no system-wide single point of failure.
 
-Full docs, architecture, and source: **https://github.com/AayushGour/terminal-hub**
+## Table of contents
+
+- [Install](#install)
+- [Features](#features)
+- [How it works](#how-it-works)
+- [Platform support](#platform-support)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Update](#update)
+- [Uninstall](#uninstall)
+- [Roadmap](#roadmap)
+- [Security](#security)
+- [License](#license)
 
 ## Install
 
@@ -16,33 +36,117 @@ npm i -g @term-hub/term-hub
 
 This installs the `term-hub` and `hub` commands and registers a launcher in your OS apps menu (Launchpad/Spotlight on macOS, the app grid on Linux, the Start Menu on Windows).
 
+- **Launch the GUI:** run `term-hub`, or click **Terminal Hub** in your apps menu. The install registers it automatically.
+- **Use the CLI:** `hub status`, `hub kill <id>`, `hub update`, `hub uninstall`, …
+
+On **first launch**, Terminal Hub asks to enable capture — click **Enable**, then open a new terminal and it shows up.
+
+`npm i -g @term-hub/term-hub` pulls in exactly one platform-specific binary package (`@term-hub/darwin-arm64`, `@term-hub/darwin-x64`, `@term-hub/linux-x64`, or `@term-hub/linux-arm64`) via `optionalDependencies` — npm resolves this automatically based on your OS/CPU, so you never download binaries for a platform you're not on.
+
+## Features
+
+**Capture & control**
+- **Auto-capture** every interactive shell via a one-time, consent-gated shell-rc hook.
+- **Two views of one shell** — drive a session from hub *and* from the terminal it was spawned in.
+- **Spawn hub-owned sessions** that persist independently of any terminal.
+- **Session buckets** — Healthy / Ghost (dead socket) / Orphan (live, no record), so nothing gets lost.
+
+**The canvas**
+- Terminals are **floating windows** — drag the title bar to move, drag the corner to resize.
+- **Infinite pannable / zoomable canvas** — drag empty space to pan, ⌘/Ctrl-scroll to zoom, **Fit** to frame them all.
+- Attach / **Detach** (stop viewing, session keeps running) and **Kill** (end the shell), with in-button progress.
+
+**Correct & safe**
+- **No single point of failure** — each session owns its own pty in a detached process; killing the router never kills a shell.
+- **Authenticated** — per-install token + same-uid peer-credential check on every socket.
+- **Real terminal behavior** — raw-mode passthrough (arrow keys, tab-completion, Ctrl-C all work), no double-echo.
+- **Reversible** — uninstall reverts the rc change, removes `~/.hub`, and removes the installed app.
+- **Self-updating GUI** — the desktop app checks for, downloads, verifies (Ed25519-signed), and installs new versions of itself; no reinstall needed.
+
+## How it works
+
+- **`hub-relay`** — one process per session. It **owns the pty** and a headless vt100 screen (for replay), fully detached. Because the shell lives here, the router can die and restart without touching your shells.
+- **`hub-daemon`** — a non-pty **reverse-proxy router** over a single unix socket. It knows every session and fans viewers out to the right relay. It owns no pty, so it is never a single point of failure.
+- **`hub-cli` (`hub`)** — install / uninstall / update / kill / status. Owns the rc-file editing (marker-guarded, byte-exact backup, edit-preserving restore) and autostart (launchd on macOS, systemd on Linux).
+- **`hub-app`** — the desktop GUI: an infinite canvas of terminal windows, per-tile connection to the daemon.
+
+## Platform support
+
+| Platform | Status | Notes |
+|---|:---:|---|
+| **macOS** (Apple Silicon & Intel) | ✅ Supported | launchd autostart, real signed `.app` bundle, self-updating |
+| **Linux** (x86_64 & arm64) | ✅ Supported | systemd user unit, AppImage, self-updating |
+| **Windows** | 🚧 In progress | CLI/engine work is underway; no GUI binaries published yet |
+
+Notes:
+- **macOS:** the app is ad-hoc signed (no Developer ID yet) — Gatekeeper won't complain about a locally-built or self-updated copy, but a fresh download from a browser may show an "unidentified developer" warning once.
+- **Linux:** the GUI needs the webkit runtime — `sudo apt install libwebkit2gtk-4.1-0` (Debian/Ubuntu) or `sudo dnf install webkit2gtk4.1` (Fedora); the launcher tells you if it's missing.
+- **Windows:** binaries aren't published yet — see [Roadmap](#roadmap).
+
 ## Usage
 
-- **Launch the GUI:** run `term-hub`, or click **Terminal Hub** in your apps menu.
-- **Enable capture:** on first launch, click **Enable** — then open a new terminal and it shows up automatically.
-- **Manage from the CLI:**
+- **Capture a terminal** — just open a new terminal after enabling. It appears under **Healthy** as an `External` session.
+- **Open a tile** — click a session (or **Open**) to bring up its live terminal on the canvas.
+- **Move / resize** — drag the title bar to move a window; drag the bottom-right corner to resize (the shell's size follows).
+- **Pan / zoom** — drag empty canvas to pan, ⌘/Ctrl-scroll to zoom toward the cursor, **Fit** to frame all windows.
+- **New hub session** — **+ New session** spawns a hub-owned shell that persists until killed.
+- **Detach vs Kill** — **Detach** stops viewing (the session keeps running); **Kill** ends the shell for everyone.
+- **CLI:**
   ```bash
   hub status              # list live sessions (healthy / ghost / orphan)
   hub kill <id>            # end a session's shell
-  hub update               # swap in a freshly built hub, in place, without dropping live sessions
-  hub uninstall            # revert everything
   ```
 
-## Platform notes
+## Configuration
 
-- **macOS:** the launcher isn't quarantined, so there's no Gatekeeper warning and no code-signing needed.
-- **Linux:** the GUI needs the webkit runtime — if the window doesn't open, `sudo apt install libwebkit2gtk-4.1-0` (Debian/Ubuntu) or `sudo dnf install webkit2gtk4.1` (Fedora).
-- **Windows:** GUI binaries are on the roadmap; not yet published.
+- **Bypass capture for one shell:** `HUB_DISABLE=1` in the environment skips the hook.
+- **Turn capture off globally:** uninstall (below), or comment out the marked block in your rc file.
+- **Scrollback buffer:** set per-tile scrollback in the app's Settings (gear icon, bottom of the sidebar) — applies to newly opened tiles.
+- **Update prompts:** the app checks for updates on launch and every 24h while open; accepting a prompt restarts the app onto the new version.
 
-`npm i -g @term-hub/term-hub` pulls in exactly one platform-specific binary package (`@term-hub/darwin-arm64`, `@term-hub/darwin-x64`, `@term-hub/linux-x64`, or `@term-hub/linux-arm64`) via `optionalDependencies` — npm resolves this automatically based on your OS/CPU, so you never download binaries for a platform you're not on.
+## Update
 
-## Uninstall
+The desktop app **self-updates** — it checks for new versions automatically and prompts you to restart when one's available. You don't need to reinstall via npm for GUI updates.
+
+The CLI engine can also be swapped in place without dropping live sessions:
 
 ```bash
-hub uninstall            # revert the shell-rc capture hook, stop the background daemon, delete ~/.hub
-npm rm -g @term-hub/term-hub   # remove the CLI + apps-menu entry
+hub update --bin-src <dir> [--yes]
 ```
 
+- `--bin-src <dir>` — copies `hub`, `hub-daemon`, `hub-relay` from `<dir>` into `~/.hub/bin`. Omit it to leave the binaries on disk untouched and just restart the daemon.
+- `--yes` — skip the confirmation prompt.
+
+Under the hood: the daemon *process* is stopped and a fresh one started (binaries are swapped via an atomic rename). Your terminals' shells and ptys are owned by independent relay processes that are never touched — the new daemon re-discovers every still-running session on its own startup. Expect a sub-second window where `hub status` / the GUI can't reach the daemon; the sessions themselves never blink.
+
+Requires a prior `hub install`; running it without one fails with a clear error rather than doing anything.
+
+## Uninstall
+
+- **From the app:** Settings → **Uninstall hub & remove app** — reverts the rc line (preserving any edits you made after install), stops the service, deletes `~/.hub`, and removes the installed app.
+- **From the CLI:**
+  ```bash
+  hub uninstall                    # revert the shell-rc capture hook, stop the daemon, delete ~/.hub
+  npm rm -g @term-hub/term-hub     # remove the CLI + the installed GUI app + apps-menu entry
+  ```
+
+Either path is a complete, equivalent teardown — `npm uninstall` and the in-app button both leave the exact same clean state. Uninstall is surgical: it removes **only** hub's own block from your rc file and leaves everything else untouched.
+
+## Roadmap
+
+- **Windows support (in progress)** — the current engine leans on POSIX (unix sockets, `fork`/`setsid`, termios). Windows needs named-pipe transport, a `CreateProcess`-based detach, console-mode raw handling, a PowerShell-profile capture hook, Windows peer-credential auth, and Task Scheduler autostart.
+- **Layouts & workspaces** — save/restore canvas arrangements; named workspaces.
+- **Persistence options** — opt-in "keep external sessions alive after their terminal closes."
+- **Canvas polish** — edge-resize (not just corner), snap/tiling helpers, minimap.
+- **Remote sessions** — securely attach to relays on another host.
+
+## Security
+
+- Every daemon/relay socket requires a per-install token (`~/.hub/token`, mode 0600) **and** a same-uid peer-credential check — a different user can't read the token or connect.
+- Capture is off until you consent, and the injected rc block is guarded (`HUB_ACTIVE` / `HUB_DISABLE` / interactive / tty / `command -v hub`) so it degrades safely and never bricks your shell.
+- The daemon owns no pty and never sees your shell's environment on the wire.
+- The desktop app only ever installs updates whose Ed25519 signature verifies against a pinned public key — a tampered or unsigned build is rejected, both on first install and on every self-update.
+
 ## License
 
 MIT

package/lib/updater-pubkey.js

@@ -0,0 +1,5 @@
+// Same public key as hub/app/src-tauri/tauri.conf.json's plugins.updater.pubkey.
+// Public data (not the private key) -- duplicating it here is safe; it must
+// stay byte-identical to the tauri.conf.json value or signature checks fail.
+"use strict";
+module.exports = "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDhGMTMzMTk0MUExQjdBNkUKUldSdWVoc2FsREVUajZnU2JrK1BobGlRdFphZFUrckdPTjFCdmFVTy83MmNtekhkTFdjY2J2dE8K";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@term-hub/term-hub",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Terminal Hub — capture every terminal you open and manage them all from one window. One-command cross-platform install (macOS / Linux / Windows).",
   "keywords": [
     "terminal",
@@ -20,6 +20,9 @@
   "license": "MIT",
   "author": "Aayush Gour <ag14906@gmail.com>",
   "type": "commonjs",
+  "dependencies": {
+    "tar": "^7"
+  },
   "bin": {
     "term-hub": "bin/term-hub.js",
     "hub": "bin/hub.js"
@@ -36,10 +39,10 @@
   },
   "//": "optionalDependencies: npm installs ONLY the package whose os/cpu matches the host, so a mac user downloads just the darwin binaries, etc. Versions are kept in lockstep with this package and bumped together by CI.",
   "optionalDependencies": {
-    "@term-hub/darwin-arm64": "0.1.1",
-    "@term-hub/darwin-x64": "0.1.1",
-    "@term-hub/linux-x64": "0.1.1",
-    "@term-hub/linux-arm64": "0.1.1"
+    "@term-hub/darwin-arm64": "0.1.3",
+    "@term-hub/darwin-x64": "0.1.3",
+    "@term-hub/linux-x64": "0.1.3",
+    "@term-hub/linux-arm64": "0.1.3"
   },
   "engines": {
     "node": ">=18"

package/scripts/postinstall.js

@@ -1,116 +1,280 @@
 #!/usr/bin/env node
-// Register a desktop launcher so Terminal Hub shows up in the OS apps menu
-// (Launchpad / Linux app grid / Start Menu) and is clickable, not just runnable
-// from a terminal. Best-effort: any failure here never fails `npm install`.
+// Downloads, verifies, and installs the real signed GUI bundle from the
+// latest GitHub Release -- replaces the old thin-launcher-shim approach now
+// that the app self-updates via tauri-plugin-updater. Best-effort: any
+// failure here never fails `npm install` (the CLI tools are the essential
+// part of this package; the GUI bundle is best-effort convenience).
+//
+// Install-exactly-once + atomic-swap design:
+//   1. Always fetch latest.json first (cheap) and compare its version against
+//      whatever's already installed (offline: an Info.plist field on macOS, a
+//      version sidecar file on Linux). If already current, skip the (large)
+//      download/verify/install entirely -- re-running `npm install -g`
+//      repeatedly must not redundantly re-download/re-extract every time.
+//      A failure to even reach latest.json (offline, GitHub down) is treated
+//      the same as "nothing to do" -- silent, since this runs on every
+//      `npm install` and a fully-installed, offline user must not see a
+//      scary error for a no-op.
+//   2. The actual install step never leaves a partially-written bundle at the
+//      real target path: the new bundle is staged next to the target (same
+//      filesystem, so the final step is a single atomic `rename()`), and only
+//      once staging succeeds does the swap happen. A crash/interruption
+//      before the swap leaves the OLD bundle untouched; the swap itself is a
+//      single filesystem syscall that either fully lands or doesn't happen.
 "use strict";
 
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
+const crypto = require("crypto");
+const { execFileSync } = require("child_process");
 
-const NAME = "Terminal Hub";
-const pkgDir = path.resolve(__dirname, "..");
-const assets = path.join(pkgDir, "assets");
+// Releases live in a separate public repo, not the private source repo --
+// GitHub 404s release assets on a private repo for anonymous requests, which
+// this postinstall download always is.
+const REPO = "AayushGour/terminal-hub-releases";
+const LATEST_JSON_URL = `https://github.com/${REPO}/releases/latest/download/latest.json`;
+let PUBKEY = null;
+try {
+  PUBKEY = require("../lib/updater-pubkey");
+} catch {
+  /* corrupted/partial install -- nothing safe to verify against */
+}
+if (!PUBKEY) process.exit(0);
+
+// Runs `fn`, prefixing any thrown error's message with `stageName` so a
+// failure deep in the pipeline (download vs. verify vs. install) is
+// identifiable from the one message `safe()` ultimately prints.
+function stage(stageName, fn) {
+  try {
+    return fn();
+  } catch (e) {
+    e.message = `${stageName}: ${e.message}`;
+    throw e;
+  }
+}
 
-function safe(label, fn) {
+function safe(fn) {
   try {
     fn();
   } catch (e) {
-    console.error(`Terminal Hub: could not register ${label} (${e.message}). You can still run \`term-hub\`.`);
+    console.error(`Terminal Hub: could not install the GUI (${e.message}). The \`hub\`/\`term-hub\` CLI still works; retry the GUI install later with a fresh \`npm install -g @term-hub/term-hub\`.`);
   }
 }
 
-// Resolve the GUI binary for this platform; if there isn't one, there's nothing
-// to register (e.g. optional deps were skipped, or unsupported platform).
-let appBin = null;
+// Only darwin/linux ship a real bundle today (win32 has no prebuilt binary
+// at all yet -- resolve.js's SUPPORTED set already gates that).
+if (process.platform !== "darwin" && process.platform !== "linux") process.exit(0);
+
+let hubBin = null;
 try {
-  const p = require("../lib/resolve").exe("hub-app");
-  if (fs.existsSync(p)) appBin = p;
+  const p = require("../lib/resolve").exe("hub");
+  if (fs.existsSync(p)) hubBin = p;
 } catch {
-  /* no binary for this platform */
+  /* CLI wasn't installed for this platform either -- nothing to verify with */
 }
-if (!appBin) process.exit(0);
-
-if (process.platform === "darwin") registerMac();
-else if (process.platform === "linux") registerLinux();
-else if (process.platform === "win32") registerWindows();
-
-function registerMac() {
-  safe("the Applications entry", () => {
-    const appDir = path.join(os.homedir(), "Applications", `${NAME}.app`);
-    const macos = path.join(appDir, "Contents", "MacOS");
-    const res = path.join(appDir, "Contents", "Resources");
-    fs.mkdirSync(macos, { recursive: true });
-    fs.mkdirSync(res, { recursive: true });
-
-    const launcher = path.join(macos, "term-hub");
-    fs.writeFileSync(launcher, `#!/bin/sh\nexec "${appBin}" "$@"\n`);
-    fs.chmodSync(launcher, 0o755);
-
-    const icns = path.join(assets, "icon.icns");
-    if (fs.existsSync(icns)) fs.copyFileSync(icns, path.join(res, "icon.icns"));
-
-    const plist = `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0"><dict>
-  <key>CFBundleName</key><string>${NAME}</string>
-  <key>CFBundleDisplayName</key><string>${NAME}</string>
-  <key>CFBundleIdentifier</key><string>dev.hub.launcher</string>
-  <key>CFBundleExecutable</key><string>term-hub</string>
-  <key>CFBundleIconFile</key><string>icon</string>
-  <key>CFBundlePackageType</key><string>APPL</string>
-</dict></plist>
-`;
-    fs.writeFileSync(path.join(appDir, "Contents", "Info.plist"), plist);
-    // A launcher .app created locally (not downloaded) isn't quarantined, so it
-    // opens with no Gatekeeper warning.
-    console.log(`Terminal Hub: added to ~/Applications — find it in Launchpad/Spotlight.`);
-  });
+if (!hubBin) process.exit(0);
+
+// Tauri's {{target}}/{{arch}} keys, e.g. "darwin-aarch64", "linux-x86_64".
+const TARGET = { darwin: "darwin", linux: "linux" }[process.platform];
+const ARCH = { x64: "x86_64", arm64: "aarch64" }[process.arch];
+const PLATFORM_KEY = ARCH ? `${TARGET}-${ARCH}` : null;
+if (!PLATFORM_KEY) process.exit(0); // unsupported arch (e.g. ia32) -- nothing to do
+
+// Numeric-aware "a >= b" for plain "x.y.z" version strings (no pre-release/
+// build-metadata handling -- this project doesn't publish those).
+function versionAtLeast(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i] || 0, y = pb[i] || 0;
+    if (x !== y) return x > y;
+  }
+  return true; // equal
+}
+
+function installedVersionMac() {
+  const plistPath = path.join(os.homedir(), "Applications", "Terminal Hub.app", "Contents", "Info.plist");
+  try {
+    const xml = fs.readFileSync(plistPath, "utf8");
+    const m = xml.match(/<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/);
+    return m ? m[1] : null;
+  } catch {
+    return null; // not installed, or unreadable -- treat as "needs install"
+  }
+}
+
+function installedVersionLinux() {
+  const versionFile = path.join(os.homedir(), ".local", "share", "term-hub", "hub-app.version");
+  try {
+    return fs.readFileSync(versionFile, "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// Fetching latest.json is the one step that runs unconditionally on every
+// `npm install`, including when there's nothing to do -- so its failure
+// (offline, GitHub unreachable) must be silent, not routed through safe()'s
+// error message.
+let manifest = null;
+try {
+  manifest = fetchJsonSync(LATEST_JSON_URL);
+} catch {
+  process.exit(0);
+}
+
+const entry = manifest.platforms && manifest.platforms[PLATFORM_KEY];
+if (!entry) process.exit(0); // no release artifact for this platform/arch yet
+
+const installed = process.platform === "darwin" ? installedVersionMac() : installedVersionLinux();
+if (installed && versionAtLeast(installed, manifest.version)) {
+  process.exit(0); // already current -- install exactly once, never redundantly re-download/re-extract
 }
 
-function registerLinux() {
-  safe("the applications menu entry", () => {
-    const appsDir = path.join(os.homedir(), ".local", "share", "applications");
-    const iconsDir = path.join(os.homedir(), ".local", "share", "icons");
-    fs.mkdirSync(appsDir, { recursive: true });
-    fs.mkdirSync(iconsDir, { recursive: true });
-
-    const png = path.join(assets, "icon.png");
-    let icon = "utilities-terminal";
-    if (fs.existsSync(png)) {
-      fs.copyFileSync(png, path.join(iconsDir, "term-hub.png"));
-      icon = "term-hub";
+safe(() => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hub-app-"));
+  try {
+    const tmpFile = path.join(tmpDir, "artifact");
+    stage("download", () => downloadSync(entry.url, tmpFile));
+
+    stage("signature verification", () =>
+      execFileSync(
+        hubBin,
+        ["verify-update-signature", "--artifact", tmpFile, "--sig-b64", entry.signature, "--pubkey-b64", PUBKEY],
+        { stdio: ["ignore", "ignore", "pipe"] },
+      ), // throws on non-zero exit
+    );
+
+    stage(process.platform === "darwin" ? "macOS install" : "Linux install", () => {
+      if (process.platform === "darwin") installMacAtomic(tmpFile);
+      else installLinuxAtomic(tmpFile, manifest.version);
+    });
+
+    console.log(`Terminal Hub: GUI installed (v${manifest.version}).`);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+function fetchJsonSync(url) {
+  // Node's global fetch (18+) is async-only; this script's callers (npm
+  // lifecycle hooks) don't await, so route through a tiny sync XHR-style
+  // wait using Atomics on a worker would be overkill here -- instead use
+  // execFileSync + curl, which every darwin/linux target already ships.
+  const out = execFileSync("curl", ["-fsSL", url], { encoding: "utf8" });
+  return JSON.parse(out);
+}
+
+function downloadSync(url, dest) {
+  execFileSync("curl", ["-fsSL", "-o", dest, url]);
+}
+
+// Extract the new bundle into a staging dir NEXT TO the real target (same
+// filesystem => the commit step is a single atomic rename()), then swap:
+// old bundle (if any) is renamed aside as a backup, the staged bundle is
+// renamed into the real target path, and only then is the backup removed.
+// If the process dies at any point before "rename staged -> target"
+// completes, the target path still holds the complete OLD bundle (or never
+// existed at all) -- it can never be left half-extracted.
+function installMacAtomic(tarGzPath) {
+  const tar = require("tar");
+  const appsDir = path.join(os.homedir(), "Applications");
+  const appDir = path.join(appsDir, "Terminal Hub.app");
+  fs.mkdirSync(appsDir, { recursive: true });
+
+  // A prior run hard-killed between the two renames below would leave one of
+  // these behind; sweep them so they don't accumulate across installs.
+  for (const name of fs.readdirSync(appsDir)) {
+    if (name.startsWith(".hub-stage-") || name.startsWith(".hub-backup-")) {
+      try {
+        fs.rmSync(path.join(appsDir, name), { recursive: true, force: true });
+      } catch {
+        /* best-effort sweep; not this install's problem if it fails */
+      }
+    }
+  }
+
+  const stageDir = path.join(appsDir, `.hub-stage-${crypto.randomBytes(6).toString("hex")}`);
+  fs.mkdirSync(stageDir, { recursive: true });
+  let backupDir = null;
+  let committed = false;
+  try {
+    tar.extract({ file: tarGzPath, cwd: stageDir, sync: true });
+    const stagedApp = path.join(stageDir, "Terminal Hub.app");
+    if (!fs.existsSync(stagedApp)) throw new Error("extracted archive did not contain Terminal Hub.app");
+
+    if (fs.existsSync(appDir)) {
+      backupDir = path.join(appsDir, `.hub-backup-${crypto.randomBytes(6).toString("hex")}`);
+      fs.renameSync(appDir, backupDir); // still same filesystem -- atomic
+    }
+    fs.renameSync(stagedApp, appDir); // the commit point -- install has now succeeded
+    committed = true;
+    console.log("Terminal Hub: added to ~/Applications — find it in Launchpad/Spotlight.");
+  } catch (e) {
+    // Roll back: if we'd already moved the old app aside but never reached
+    // the commit rename, put it back so the user isn't left without an app.
+    if (!committed && backupDir && fs.existsSync(backupDir) && !fs.existsSync(appDir)) {
+      fs.renameSync(backupDir, appDir);
     }
+    throw e;
+  } finally {
+    fs.rmSync(stageDir, { recursive: true, force: true });
+    // Cleanup after a successful commit is best-effort -- it must never turn
+    // an already-succeeded install into a reported failure.
+    if (committed && backupDir) {
+      try {
+        fs.rmSync(backupDir, { recursive: true, force: true });
+      } catch {
+        /* orphaned backup dir; harmless, swept on the next install */
+      }
+    }
+  }
+}
 
-    const desktop = `[Desktop Entry]
+// AppImages are a single file, so the atomic swap is simpler than macOS's
+// directory case: write the new file next to the target (same dir => same
+// filesystem) and rename() it onto the fixed path in one step.
+function installLinuxAtomic(appImagePath, version) {
+  const fixedDir = path.join(os.homedir(), ".local", "share", "term-hub");
+  const fixedPath = path.join(fixedDir, "hub-app.AppImage");
+  fs.mkdirSync(fixedDir, { recursive: true });
+
+  const stagedPath = path.join(fixedDir, `.hub-app.AppImage.tmp-${crypto.randomBytes(6).toString("hex")}`);
+  try {
+    fs.copyFileSync(appImagePath, stagedPath);
+    fs.chmodSync(stagedPath, 0o755);
+    fs.renameSync(stagedPath, fixedPath); // the commit point -- same filesystem, atomic
+  } finally {
+    fs.rmSync(stagedPath, { force: true }); // no-op once renamed away; catches a failed rename
+  }
+
+  const iconsDir = path.join(os.homedir(), ".local", "share", "icons");
+  fs.mkdirSync(iconsDir, { recursive: true });
+  const png = path.join(__dirname, "..", "assets", "icon.png");
+  let icon = "utilities-terminal";
+  if (fs.existsSync(png)) {
+    fs.copyFileSync(png, path.join(iconsDir, "term-hub.png"));
+    icon = "term-hub";
+  }
+
+  const appsDir = path.join(os.homedir(), ".local", "share", "applications");
+  fs.mkdirSync(appsDir, { recursive: true });
+  const desktop = `[Desktop Entry]
 Type=Application
-Name=${NAME}
+Name=Terminal Hub
 Comment=Capture and manage all your terminals
-Exec="${appBin}" %U
+Exec="${fixedPath}" %U
 Icon=${icon}
 Terminal=false
 Categories=Utility;System;TerminalEmulator;
 `;
-    fs.writeFileSync(path.join(appsDir, "term-hub.desktop"), desktop);
-    console.log("Terminal Hub: added to your applications menu.");
-  });
-}
+  fs.writeFileSync(path.join(appsDir, "term-hub.desktop"), desktop);
 
-function registerWindows() {
-  safe("the Start Menu shortcut", () => {
-    const { execFileSync } = require("child_process");
-    const appData = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
-    const startMenu = path.join(appData, "Microsoft", "Windows", "Start Menu", "Programs");
-    fs.mkdirSync(startMenu, { recursive: true });
-    const lnk = path.join(startMenu, `${NAME}.lnk`);
-    const ico = path.join(assets, "icon.ico");
-    const q = (s) => s.replace(/'/g, "''");
-    const ps =
-      `$s=(New-Object -ComObject WScript.Shell).CreateShortcut('${q(lnk)}');` +
-      `$s.TargetPath='${q(appBin)}';` +
-      (fs.existsSync(ico) ? `$s.IconLocation='${q(ico)}';` : "") +
-      `$s.Save()`;
-    execFileSync("powershell", ["-NoProfile", "-NonInteractive", "-Command", ps], { stdio: "ignore" });
-    console.log("Terminal Hub: added to the Start Menu.");
-  });
+  // Written LAST, only once the binary + menu entry are both in place: the
+  // version-skip gate above treats this file's presence/content as "fully
+  // installed," so recording it before the desktop entry exists would let a
+  // transient desktop-entry failure go unretried on the next `npm install`.
+  fs.writeFileSync(path.join(fixedDir, "hub-app.version"), version + "\n");
+  console.log("Terminal Hub: added to your applications menu.");
 }

package/scripts/preuninstall.js

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
-// Remove the desktop launcher created by postinstall.js on `npm rm -g`.
-// Best-effort; never throws.
+// Full-parity uninstall: `npm uninstall -g` must leave the same end state as
+// clicking "Uninstall hub & remove app" in the GUI -- rc files restored,
+// daemon stopped, ~/.hub deleted, the GUI bundle gone, and any running GUI
+// window force-quit. Best-effort throughout; never throws (npm lifecycle
+// hooks that exit non-zero produce noisy, confusing `npm uninstall` output).
 "use strict";
 
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
+const { execFileSync } = require("child_process");
 
-const NAME = "Terminal Hub";
 const rm = (p) => {
   try {
     fs.rmSync(p, { recursive: true, force: true });
@@ -16,12 +19,71 @@ const rm = (p) => {
   }
 };
 
-if (process.platform === "darwin") {
-  rm(path.join(os.homedir(), "Applications", `${NAME}.app`));
-} else if (process.platform === "linux") {
-  rm(path.join(os.homedir(), ".local", "share", "applications", "term-hub.desktop"));
-  rm(path.join(os.homedir(), ".local", "share", "icons", "term-hub.png"));
-} else if (process.platform === "win32") {
-  const appData = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
-  rm(path.join(appData, "Microsoft", "Windows", "Start Menu", "Programs", `${NAME}.lnk`));
+const hubHome = path.join(os.homedir(), ".hub");
+
+function isHubCaptureInstalled() {
+  return (
+    fs.existsSync(path.join(hubHome, "install-manifest.json")) ||
+    fs.existsSync(path.join(hubHome, "bin", "hub"))
+  );
+}
+
+function resolveHubBinary() {
+  const selfContained = path.join(hubHome, "bin", "hub");
+  if (fs.existsSync(selfContained)) return selfContained;
+  try {
+    return require("../lib/resolve").exe("hub");
+  } catch {
+    return null;
+  }
+}
+
+function revertHubCapture() {
+  if (!isHubCaptureInstalled()) return; // nothing to revert
+  const hubBin = resolveHubBinary();
+  if (!hubBin) {
+    console.error("Terminal Hub: hub capture looks installed but no `hub` binary could be found to revert it — ~/.hub was left in place.");
+    return;
+  }
+  try {
+    execFileSync(hubBin, ["uninstall", "--yes"], { stdio: ["ignore", "ignore", "pipe"] });
+  } catch (e) {
+    console.error(`Terminal Hub: \`hub uninstall\` failed (${e.message}) — some state under ~/.hub or your shell rc may remain. Run \`hub uninstall\` manually to retry.`);
+  }
+}
+
+function forceQuitRunningApp() {
+  if (process.platform === "darwin") {
+    try {
+      execFileSync("pkill", ["-f", "Terminal Hub.app/Contents/MacOS/hub-app"], { stdio: "ignore" });
+    } catch {
+      /* pkill exits non-zero when nothing matches -- expected, not an error */
+    }
+  } else if (process.platform === "linux") {
+    const fixedPath = path.join(os.homedir(), ".local", "share", "term-hub", "hub-app.AppImage");
+    try {
+      execFileSync("pkill", ["-f", fixedPath], { stdio: "ignore" });
+    } catch {
+      /* same as above */
+    }
+  }
 }
+
+function removeGuiBundle() {
+  if (process.platform === "darwin") {
+    rm(path.join(os.homedir(), "Applications", "Terminal Hub.app"));
+  } else if (process.platform === "linux") {
+    rm(path.join(os.homedir(), ".local", "share", "term-hub", "hub-app.AppImage"));
+    rm(path.join(os.homedir(), ".local", "share", "term-hub", "hub-app.version"));
+    rm(path.join(os.homedir(), ".local", "share", "applications", "term-hub.desktop"));
+    rm(path.join(os.homedir(), ".local", "share", "icons", "term-hub.png"));
+  } else if (process.platform === "win32") {
+    // Unaffected by this change -- Windows GUI distribution is still phase 2.
+    const appData = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    rm(path.join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Terminal Hub.lnk"));
+  }
+}
+
+revertHubCapture();
+forceQuitRunningApp();
+removeGuiBundle();