@term-hub/term-hub 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,50 @@
+<p align="center"><img src="https://raw.githubusercontent.com/AayushGour/terminal-hub/main/assets/imgs/terminal-cube.svg" alt="Terminal Hub logo" width="120"></p>
+
+# Terminal Hub
+
+**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.
+
+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**
+
+## Install
+
+```bash
+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).
+
+## 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:**
+  ```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
+
+- **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.
+
+`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.
+
+## Uninstall
+
+```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
+```
+
+## License
+
+MIT

package/bin/term-hub.js

@@ -1,21 +1,38 @@
 #!/usr/bin/env node
-// Launch the Terminal Hub GUI. Detaches so the terminal returns immediately.
+// Launch the Terminal Hub GUI (the real installed bundle -- postinstall.js
+// puts it at a fixed location per platform, it is NOT shipped as a raw
+// binary inside this npm package anymore, see Task 11's D1 change).
 "use strict";
 
 const { spawn } = require("child_process");
-const { exe } = require("../lib/resolve");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
 
-let bin;
-try {
-  bin = exe("hub-app");
-} catch (e) {
-  console.error(String(e.message || e));
-  process.exit(1);
+function launchDarwin() {
+  const appPath = path.join(os.homedir(), "Applications", "Terminal Hub.app");
+  if (!fs.existsSync(appPath)) {
+    console.error(
+      `Terminal Hub: the app isn't installed at ${appPath}. Retry the GUI install with a fresh \`npm install -g @term-hub/term-hub\`.`
+    );
+    process.exit(1);
+  }
+  const extraArgs = process.argv.slice(2);
+  return spawn("open", [appPath, ...(extraArgs.length ? ["--args", ...extraArgs] : [])], {
+    stdio: "ignore",
+    detached: true,
+  });
 }
 
-// On Linux the GUI needs the webkit2gtk runtime; hint if it's obviously missing.
-if (process.platform === "linux") {
-  const fs = require("fs");
+function launchLinux() {
+  const appImagePath = path.join(os.homedir(), ".local", "share", "term-hub", "hub-app.AppImage");
+  if (!fs.existsSync(appImagePath)) {
+    console.error(
+      `Terminal Hub: the app isn't installed at ${appImagePath}. Retry the GUI install with a fresh \`npm install -g @term-hub/term-hub\`.`
+    );
+    process.exit(1);
+  }
+  // Same webkit2gtk hint as before -- the AppImage needs it at runtime.
   const hasWebkit = ["/usr/lib", "/usr/lib/x86_64-linux-gnu", "/usr/lib/aarch64-linux-gnu", "/usr/lib64"].some(
     (d) => {
       try {
@@ -32,12 +49,19 @@ if (process.platform === "linux") {
         "  Fedora:         sudo dnf install webkit2gtk4.1"
     );
   }
+  return spawn(appImagePath, process.argv.slice(2), { stdio: "ignore", detached: true });
+}
+
+let child;
+if (process.platform === "darwin") {
+  child = launchDarwin();
+} else if (process.platform === "linux") {
+  child = launchLinux();
+} else {
+  console.error("Terminal Hub: the GUI isn't available on this platform yet.");
+  process.exit(1);
 }
 
-const child = spawn(bin, process.argv.slice(2), {
-  stdio: "ignore",
-  detached: true,
-});
 child.on("error", (err) => {
   console.error(`Terminal Hub: failed to launch (${err.message}).`);
   process.exit(1);

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.0",
+  "version": "0.1.2",
   "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",
@@ -11,10 +11,18 @@
     "terminal-manager",
     "tauri"
   ],
-  "homepage": "https://github.com/your-org/term-hub#readme",
+  "homepage": "https://github.com/AayushGour/terminal-hub#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AayushGour/terminal-hub.git",
+    "directory": "hub/npm/term-hub"
+  },
   "license": "MIT",
-  "author": "TODO your name <ag14906@gmail.com>",
+  "author": "Aayush Gour <ag14906@gmail.com>",
   "type": "commonjs",
+  "dependencies": {
+    "tar": "^7"
+  },
   "bin": {
     "term-hub": "bin/term-hub.js",
     "hub": "bin/hub.js"
@@ -31,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.0",
-    "@term-hub/darwin-x64": "0.1.0",
-    "@term-hub/linux-x64": "0.1.0",
-    "@term-hub/linux-arm64": "0.1.0"
+    "@term-hub/darwin-arm64": "0.1.2",
+    "@term-hub/darwin-x64": "0.1.2",
+    "@term-hub/linux-x64": "0.1.2",
+    "@term-hub/linux-arm64": "0.1.2"
   },
   "engines": {
     "node": ">=18"

package/scripts/postinstall.js

@@ -1,116 +1,277 @@
 #!/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");
+const REPO = "AayushGour/terminal-hub";
+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();