@term-hub/term-hub 0.1.2 → 0.1.4

package/README.md

@@ -1,14 +1,32 @@
-<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>
+<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 Hub
+<h1 align="center">Terminal Hub</h1>
 
-**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.
+<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
 
@@ -18,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@term-hub/term-hub",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",
@@ -39,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.2",
-    "@term-hub/darwin-x64": "0.1.2",
-    "@term-hub/linux-x64": "0.1.2",
-    "@term-hub/linux-arm64": "0.1.2"
+    "@term-hub/darwin-arm64": "0.1.4",
+    "@term-hub/darwin-x64": "0.1.4",
+    "@term-hub/linux-x64": "0.1.4",
+    "@term-hub/linux-arm64": "0.1.4"
   },
   "engines": {
     "node": ">=18"

package/scripts/postinstall.js

@@ -29,7 +29,10 @@ const path = require("path");
 const crypto = require("crypto");
 const { execFileSync } = require("child_process");
 
-const REPO = "AayushGour/terminal-hub";
+// 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 {