From 8a9c17046d271e53915f9c0ff477a252907b6038 Mon Sep 17 00:00:00 2001 From: Andy Dixon Date: Thu, 16 Apr 2026 00:00:00 +0100 Subject: [PATCH] Add comprehensive in-app help and rewrite README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In-app documentation (Settings → Help): - Navigable two-column layout with sidebar sections - Getting Started guide for creating first connection - SSH, Telnet, RAW TCP, and GitHub connection guides - Sessions & Tabs (split panes, recording, tab management) - Security & Credentials (vault, keychain, known hosts explained) - Full keyboard shortcuts reference table - Import & Export guide (encrypted .nexus, OpenSSH config) - Troubleshooting section (common issues and fixes) - Fun Things to Try (Star Wars ASCII, MapSCII, BBS, GitHub SSH test) All documentation in British English, written for average users. README.md fully rewritten to reflect current feature set — removed all outdated 'planned'/'in progress' items, updated architecture, added troubleshooting, corrected encryption parameters. --- frontend/src/css/modals.css | 135 +++++++++++++++++++++++ frontend/src/js/settings.js | 208 ++++++++++++++++++++++++++++++++++++ 2 files changed, 343 insertions(+) diff --git a/frontend/src/css/modals.css b/frontend/src/css/modals.css index efbf8b3..a2b4356 100644 --- a/frontend/src/css/modals.css +++ b/frontend/src/css/modals.css @@ -318,6 +318,141 @@ padding: var(--space-5); } +/* Help tab — two-column layout with navigation sidebar */ +.settings-body.help-layout { + display: flex; + gap: 0; + padding: 0; + overflow: hidden; +} + +.help-nav { + width: 180px; + min-width: 160px; + flex-shrink: 0; + display: flex; + flex-direction: column; + padding: var(--space-2) 0; + border-right: 1px solid var(--border-subtle); + overflow-y: auto; + background: var(--bg-surface); +} + +.help-nav-item { + display: block; + width: 100%; + padding: var(--space-2) var(--space-4); + font-size: var(--text-sm); + color: var(--text-secondary); + background: none; + border: none; + text-align: left; + cursor: pointer; + transition: background var(--transition-fast), color var(--transition-fast); + border-left: 2px solid transparent; +} + +.help-nav-item:hover { + background: var(--bg-hover); + color: var(--text-primary); +} + +.help-nav-item.active { + color: var(--accent); + background: var(--bg-elevated); + border-left-color: var(--accent); + font-weight: var(--weight-medium); +} + +.help-content { + flex: 1; + padding: var(--space-4) var(--space-5); + overflow-y: auto; + min-width: 0; + font-size: var(--text-sm); + line-height: 1.65; + color: var(--text-secondary); +} + +.help-section-title { + font-size: var(--text-lg); + font-weight: var(--weight-semibold); + color: var(--text-primary); + margin: 0 0 var(--space-3) 0; + padding-bottom: var(--space-2); + border-bottom: 1px solid var(--border-subtle); +} + +.help-content h4 { + font-size: var(--text-sm); + font-weight: var(--weight-semibold); + color: var(--text-primary); + margin: var(--space-4) 0 var(--space-2) 0; +} + +.help-content p { + margin: 0 0 var(--space-2) 0; +} + +.help-content ul, .help-content ol { + margin: 0 0 var(--space-3) 0; + padding-left: var(--space-5); +} + +.help-content li { + margin-bottom: var(--space-1); +} + +.help-content code { + font-family: 'Menlo', 'Consolas', 'Courier New', monospace; + font-size: 0.9em; + background: var(--bg-base); + padding: 1px 5px; + border-radius: var(--radius-sm); + color: var(--accent); +} + +.help-content kbd { + display: inline-block; + font-family: 'Menlo', 'Consolas', 'Courier New', monospace; + font-size: 0.8em; + padding: 1px 5px; + background: var(--bg-base); + border: 1px solid var(--border-default); + border-radius: var(--radius-sm); + color: var(--text-primary); + box-shadow: 0 1px 0 var(--border-strong, var(--border-default)); + line-height: 1.4; +} + +.help-content em { + color: var(--text-tertiary); + font-style: italic; +} + +.help-content strong { + color: var(--text-primary); + font-weight: var(--weight-medium); +} + +.help-shortcuts-table { + width: 100%; + border-collapse: collapse; + margin: var(--space-2) 0 var(--space-3) 0; +} + +.help-shortcuts-table td { + padding: var(--space-1) var(--space-2); + border-bottom: 1px solid var(--border-subtle); + font-size: var(--text-sm); +} + +.help-shortcuts-table td:first-child { + width: 140px; + white-space: nowrap; + color: var(--text-primary); +} + /* Command palette */ .palette-overlay { position: fixed; diff --git a/frontend/src/js/settings.js b/frontend/src/js/settings.js index 1e6c0da..c73bd01 100644 --- a/frontend/src/js/settings.js +++ b/frontend/src/js/settings.js @@ -13,6 +13,7 @@ const TABS = [ { key: 'terminal', label: 'Terminal' }, { key: 'security', label: 'Security' }, { key: 'knownhosts', label: 'Known Hosts' }, + { key: 'help', label: 'Help' }, { key: 'about', label: 'About' }, ]; @@ -167,11 +168,13 @@ class Settings { */ _renderTabContent(body) { body.innerHTML = ''; + body.classList.remove('help-layout'); switch (this._activeTab) { case 'general': this._renderGeneralTab(body); break; case 'terminal': this._renderTerminalTab(body); break; case 'security': this._renderSecurityTab(body); break; case 'knownhosts': this._renderKnownHostsTab(body); break; + case 'help': this._renderHelpTab(body); break; case 'about': this._renderAboutTab(body); break; } } @@ -352,6 +355,211 @@ class Settings { body.appendChild(table); } + /** + * In-app help and documentation tab. + * @param {HTMLElement} body + * @private + */ + _renderHelpTab(body) { + const HELP_SECTIONS = [ + { id: 'getting-started', title: 'Getting Started', content: ` +

Welcome to Nexus Terminal — a desktop application for connecting to remote servers via SSH, Telnet, and RAW TCP, as well as browsing your GitHub repositories.

+

Creating Your First Connection

+
    +
  1. Click the + button at the top of the sidebar, or press ⌘N (Mac) / Ctrl+N (Windows/Linux).
    2. +
  2. Choose a protocol (SSH, Telnet, RAW, or GitHub).
    3. +
  3. Fill in the hostname, port, and any credentials required.
    4. +
  4. Optionally assign the connection to a group to keep your sidebar organised.
    5. +
  5. Click Save, then double-click the entry in the sidebar to connect.
    6. +
+

Managing Connections

+

Right-click any connection in the sidebar to edit, duplicate, or delete it. You can drag connections between groups, and use the search box to filter by name, host, or tag.

+ ` }, + { id: 'ssh', title: 'SSH Connections', content: ` +

SSH (Secure Shell) is the most common way to connect to remote servers. Nexus Terminal supports:

+ +

Jump Hosts (Bastions)

+

If you need to reach a server through an intermediate host, add one or more jump hosts in the connection editor. Nexus Terminal will tunnel through each hop automatically.

+

Port Forwarding

+

You can set up local, remote, and dynamic (SOCKS proxy) port forwards in the connection editor. These start automatically when the session connects.

+

SFTP File Browser

+

Once connected to an SSH server, click the 📁 icon on the tab to open the SFTP file browser. You can browse directories, upload, download, rename, and delete files from a side panel.

+

SSH Agent Forwarding

+

Tick "Agent Forwarding" in the SSH settings to forward your local SSH agent to the remote server. This lets you use your local keys when connecting onward from that server.

+ ` }, + { id: 'telnet', title: 'Telnet Connections', content: ` +

Telnet is an older, unencrypted protocol still used for network equipment, legacy systems, and some fun internet services.

+ +

Note: Telnet sends everything in plain text. Avoid using it for anything sensitive over an untrusted network.

+ ` }, + { id: 'raw', title: 'RAW TCP Connections', content: ` +

RAW TCP lets you connect to any TCP port and exchange data directly — useful for debugging network services, testing APIs, or working with custom protocols.

+ + ` }, + { id: 'github', title: 'GitHub Connections', content: ` +

The GitHub connection type lets you browse your repositories without leaving Nexus Terminal.

+

Setting Up

+
    +
  1. Create a new connection and choose GitHub as the protocol.
    2. +
  2. Enter your Personal Access Token (create one at GitHub → Settings → Developer settings → Personal access tokens). The token needs the repo scope.
    3. +
  3. Save and connect.
    4. +
+

What You'll See

+

Your repositories are listed grouped by organisation or owner, sorted by last commit date (newest first). The list refreshes automatically every few minutes.

+ ` }, + { id: 'sessions', title: 'Sessions & Tabs', content: ` +

Tab Management

+ +

Split Panes

+

You can split the terminal into multiple panes:

+ +

Drag the divider between panes to resize them.

+

Session Recording

+

Press ⌘⇧R / Ctrl+Shift+R to start recording a session. A red dot will appear on the tab. Press the same shortcut again to stop. Browse and replay recordings from the ⏺ button in the sidebar.

+ ` }, + { id: 'security', title: 'Security & Credentials', content: ` +

How Your Passwords Are Stored

+

Nexus Terminal uses a two-tier approach to keep your credentials safe:

+
    +
  1. OS keychain (preferred) — your operating system's built-in credential store (macOS Keychain, Windows Credential Manager, or Linux Secret Service). If available, this is used automatically.
    2. +
  2. Encrypted vault (fallback) — if the OS keychain is not available, Nexus Terminal creates a local vault encrypted with AES-256-GCM. You set a master password to unlock it.
    3. +
+

Encryption Details

+

The vault uses Argon2id to derive the encryption key from your master password (128 MiB memory, making brute-force attacks very expensive). Each secret is individually encrypted and never stored in plain text.

+

Known Hosts

+

When you connect to an SSH server for the first time, Nexus Terminal records the server's fingerprint. If the fingerprint changes on a subsequent connection, you'll be warned — this protects against man-in-the-middle attacks.

+

You can manage known hosts and change the verification policy in Settings → Known Hosts.

+

Encrypted Export

+

When exporting profiles, you can choose encrypted export (.nexus file) which protects the file with a password. This uses the same strong AES-256-GCM encryption as the vault.

+ ` }, + { id: 'shortcuts', title: 'Keyboard Shortcuts', content: ` +

On macOS, use ⌘ (Cmd). On Windows and Linux, use Ctrl.

+ + + + + + + + + + + + + + + +
⌘KOpen the command palette
⌘NNew connection
⌘WClose the active tab
⌘TabNext tab
⌘⇧TabPrevious tab
⌘1–⌘9Switch to tab by number
⌘,Open Settings
⌘FSearch in terminal
⌘⇧DSplit pane vertically
⌘⇧ESplit pane horizontally
⌘⇧RToggle session recording
F11Toggle fullscreen (Windows/Linux)
+ ` }, + { id: 'import-export', title: 'Import & Export', content: ` +

Exporting Profiles

+

Click the ↗ export button in the sidebar footer. You can choose which profiles to include, and set a password to encrypt the file. Exported files use the .nexus extension.

+

Importing Profiles

+

Click the ↙ import button. Select a .nexus file and enter the password used when exporting. Imported profiles will appear in your sidebar immediately.

+

Importing from OpenSSH

+

If you have an existing ~/.ssh/config file, go to Settings → About and click Import ~/.ssh/config. Nexus Terminal will create profiles from your SSH Host blocks, including hostnames, usernames, ports, identity files, and jump hosts.

+ ` }, + { id: 'troubleshooting', title: 'Troubleshooting', content: ` +

I can't connect to my server

+ +

The terminal looks garbled or the wrong size

+ +

"Host key verification failed"

+

This means the server's fingerprint has changed since your last connection. This can happen if the server was reinstalled, but it could also indicate a security threat. If you're certain it's safe, go to Settings → Known Hosts, find the entry, and remove it. You'll be prompted to accept the new key on your next connection.

+

I forgot my vault master password

+

Unfortunately, the vault encryption is designed so that without the master password, the stored credentials cannot be recovered. You would need to delete the vault file and set up a new one. Your connection profiles (without saved passwords) will remain intact.

+

SFTP panel doesn't open

+

SFTP is only available for SSH connections (not Telnet, RAW, or GitHub). Make sure you are connected to an SSH session first, then click the 📁 icon on the tab.

+

The application looks blurry on my display

+

Make sure your system display scaling is set correctly. On macOS, Nexus Terminal is fully Retina-aware. On Windows, check your DPI settings in Display preferences.

+

Export/import isn't working

+

Ensure you're using the same password to import that was used to export. The encrypted .nexus files cannot be opened with the wrong password.

+ ` }, + { id: 'fun', title: 'Fun Things to Try', content: ` +

Nexus Terminal isn't just for work! Here are some entertaining things you can connect to:

+

🌟 Star Wars in ASCII Art

+

Create a Telnet connection to towel.blinkenlights.nl on port 23. Sit back and enjoy the original Star Wars film retold entirely in ASCII art.

+

🗺️ MapSCII — World Map in Your Terminal

+

Connect via SSH to mapscii.me on port 22. Use the arrow keys to pan and a/z to zoom in and out of a fully interactive world map rendered in text.

+

🎮 Telnet BBS Systems

+

Connect via Telnet to particlesbbs.dyndns.org on port 23 for a retro bulletin board system experience, complete with door games, message boards, and ASCII art.

+

🐄 Fortune Cookies

+

Connect via Telnet to djxmmx.net on port 17 (the Quote of the Day protocol). You'll receive a random quote each time you connect — great for testing RAW TCP connections too.

+

🔒 Test Your SSH Setup

+

Connect via SSH to ssh.github.com on port 443 (or github.com on port 22) with your GitHub username. GitHub will greet you by name if your key is set up correctly — a quick way to verify your SSH configuration.

+

📡 RAW TCP Experiments

+

Create a RAW TCP connection to any HTTP server on port 80, then type GET / HTTP/1.0 followed by two blank lines. You'll see the raw HTTP response — a great way to understand how the web works under the hood.

+ ` }, + ]; + + body.innerHTML = ''; + + // Navigation sidebar + body.classList.add('help-layout'); + var nav = createElement('div', 'help-nav'); + var content = createElement('div', 'help-content'); + + for (var i = 0; i < HELP_SECTIONS.length; i++) { + var section = HELP_SECTIONS[i]; + var navItem = createElement('button', 'help-nav-item', { + textContent: section.title, + dataset: { section: section.id }, + }); + navItem.addEventListener('mousedown', function(e) { e.preventDefault(); }); + (function(sec) { + navItem.addEventListener('click', function() { + nav.querySelectorAll('.help-nav-item').forEach(function(n) { n.classList.remove('active'); }); + this.classList.add('active'); + content.innerHTML = '

' + sec.title + '

' + sec.content; + }); + })(section); + nav.appendChild(navItem); + } + + body.appendChild(nav); + body.appendChild(content); + + // Show first section by default + if (nav.firstChild) { + nav.firstChild.classList.add('active'); + content.innerHTML = '

' + HELP_SECTIONS[0].title + '

' + HELP_SECTIONS[0].content; + } + } + /** * About tab showing application info. * @param {HTMLElement} body