nterminal 1.2.0

package/README.md

@@ -0,0 +1,181 @@
+# NTerminal
+
+<img src="public/icons/app-icon-1024.png" alt="NTerminal app icon" width="96" height="96">
+
+NTerminal turns your own machines into one secure browser workspace for real shells, Codex, Claude, files, and long-running terminal sessions.
+
+<img src="assets/screenshot/scr.png" alt="NTerminal workspace with split terminal panes" width="100%">
+
+NTerminal is a single-owner web terminal for machines you control. It is not a hosted shell product, not a SaaS app, and not a multi-user IDE.
+
+## How It Works
+
+```text
+Browser
+  -> Main Server
+     -> Secondary Servers
+```
+
+- **Main Server** serves the browser UI, owns login/session security, stores the server list, and proxies terminal/file traffic to secondary servers.
+- **Secondary Servers** run on additional machines and expose their local shells/files to the main server after guided onboarding.
+- Each server is a normal Node.js process connected to real host PTYs through `node-pty`.
+
+## Quick Start
+
+Clone the repo on the machine that should become the **main server**, then run:
+
+```bash
+npm run onboarding
+```
+
+Choose `main`. Onboarding installs dependencies, writes `.env`, creates secrets, sets your password and TOTP, and can build/start the service.
+
+To add another machine, clone the repo there and run the same command:
+
+```bash
+npm run onboarding
+```
+
+Choose `secondary`, enter the main server URL, log in once from the CLI, and the server registers itself in the main UI.
+
+After onboarding finishes, open the URL printed in the final summary and log in with your password plus authenticator code.
+
+See [docs/onboarding.md](docs/onboarding.md) for the full main/secondary setup flow, nginx/TLS automation, and local-only setup.
+
+After NTerminal is published to npm, package installs can use:
+
+```bash
+npm install -g nterminal
+nterminal onboarding
+```
+
+Package installs keep runtime config and state under `~/.nterminal` so package updates do not overwrite local sessions or secrets.
+Use a user-writable npm global prefix if you want in-app updates to run without sudo.
+
+## Key Features
+
+### One Workspace For Multiple Servers
+
+- Manage the main server and all secondary servers from one terminal UI.
+- Switch servers from the sidebar without losing terminal layout or pane state.
+- Keep separate tabs, split panes, detached terminals, and file context per server.
+- Run fleet updates from the UI; git checkouts and npm package installs use their own safe update paths.
+
+### Secure Personal Access
+
+- Password plus TOTP two-factor authentication.
+- Single active session: a new login revokes the previous browser session.
+- Session IP binding with subnet tolerance for common residential/CGNAT rotation.
+- Trusted devices and trusted networks for repeat access from known places.
+- Same-origin cookie and WebSocket checks for terminal/file mutation routes.
+
+### Persistent Terminal Workspace
+
+- Real host shell PTYs with tabs and split panes.
+- Refresh and temporary WebSocket reconnects reattach to active PTYs.
+- Closing a tab or pane soft-detaches it into a restorable pill instead of killing the shell.
+- Optional tmux-backed PTY persistence keeps shells alive across NTerminal Node restarts.
+- Tab titles sync with tmux window names so labels survive detach/reattach cycles.
+
+### Codex / Claude Friendly History
+
+- Mouse wheel scrolling moves terminal output history, not Codex/Claude prompt history.
+- Older tmux scrollback loads incrementally when you reach the top.
+- Supported Codex/Claude panes can continue into JSONL transcript history from `~/.codex/sessions` or `~/.claude/projects`.
+- Scroll progress, a jump-to-bottom button, mobile drag handles, and follow-tail behavior keep large outputs usable.
+
+### Files, Uploads, And Clipboard
+
+- Sidebar file explorer follows the selected pane's working directory.
+- View/edit text and Markdown files, preview browser-supported files, and reject stale overwrites.
+- Drag files or folders into the workspace to upload them into the active pane's cwd.
+- Terminal Ctrl+C copies selected text and falls through to SIGINT when nothing is selected; Ctrl+V pastes clipboard text.
+
+### Completion Notifications
+
+- In-app completion toasts appear when background commands finish.
+- Toasts can auto-dismiss, stay until dismissed, or use custom MP4/WebM videos.
+- Settings can preview built-in/uploaded videos, enable/disable them, and randomly choose from the enabled set.
+- Clicking a completion toast jumps back to the server and pane that finished.
+- Optional OS notifications are available when the page is hidden.
+
+### Mobile And PWA
+
+- iPad home-screen metadata and icons are included.
+- Mobile terminal key bar exposes Ctrl, Esc, Tab, and arrows when needed.
+- Touch scrolling controls are tuned for long terminal output.
+
+### Simple npm Toolchain
+
+- The project uses npm so source checkouts and package installs use the same package manager.
+- `npm run onboarding` runs install automatically on fresh checkouts.
+- The `nterminal` CLI entrypoint is prepared for global npm installs.
+
+## Requirements
+
+- Node.js 22 or newer.
+- Linux or macOS.
+- Native build tools required by `node-pty`.
+- Optional `tmux` for PTY persistence across Node restarts.
+
+If PTY creation fails after install, rebuild the native module:
+
+```bash
+npm rebuild node-pty --build-from-source
+```
+
+## Common Commands
+
+```bash
+npm run onboarding
+npm run service:status
+npm run service:logs
+npm run service:restart
+npm test
+npm run build
+```
+
+For production-style local operation, `npm run ctl -- <command>` wraps `scripts/nterminalctl` and manages the built server, PID file, logs, health checks, and restarts.
+
+## Documentation
+
+- [Onboarding](docs/onboarding.md): main/secondary setup, nginx, TLS, firewall, and local-only setup.
+- [Configuration](docs/configuration.md): `.env`, environment variables, and deployment examples.
+- [Operations](docs/operations.md): service control, updates, clean uninstall, verification, and troubleshooting.
+- [Terminal History](docs/terminal-history.md): tmux scrollback, alternate buffer behavior, Codex/Claude JSONL history, and large-output ergonomics.
+- [Features](docs/features.md): files, uploads, notifications, mobile controls, keyboard shortcuts, and PWA behavior.
+- [Security](SECURITY.md): supported security boundary and vulnerability reporting.
+
+## Limitations
+
+- No multi-user accounts or roles.
+- No container isolation for spawned shells by default.
+- No recovery of live PTYs after an OS reboot.
+- No Node-restart PTY persistence on hosts without `tmux`.
+- No VS Code extension host, debugger, task runner, or Git UI.
+- No package-manager distribution is published yet.
+
+## Publication Notes
+
+Keep local runtime files out of source control:
+
+- `.env`
+- `.env.*` except `.env.example`
+- `.nterminal/`
+- `.claude/`
+- `dist/`
+- logs
+- `test-results/`
+- `playwright-report/`
+
+The package metadata is prepared for npm publication. The source code is licensed under GPL-3.0-only.
+
+## Acknowledgements
+
+NTerminal is inspired by [Mansio](https://github.com/Younkyum/mansio) and [Leominal](https://github.com/jcwleo/leominal).
+
+It reworks the persistent browser terminal idea around multi-server operation, OTP and IP-bound sessions, easier onboarding, and a more browser-native terminal experience with smooth scrollback and tab management, aiming to provide a more convenient and safer workspace for developers working across multiple remote servers.
+
+## License
+
+NTerminal is licensed under GPL-3.0-only. See [LICENSE](LICENSE).

package/assets/brand/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect width="64" height="64" rx="12" ry="12" fill="#0A0A0B"/>
+  <text font-family="'JetBrains Mono', ui-monospace, monospace" font-weight="700" font-size="50" dominant-baseline="middle"><tspan x="-13.00" y="34.56" fill="#FF2A3D">{</tspan><tspan x="17.00" y="34.56" fill="#fff">n</tspan><tspan x="47.00" y="34.56" fill="#FF2A3D">}</tspan></text>
+</svg>

package/assets/brand/nterminal-mark.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32">
+  <rect width="32" height="32" rx="6" ry="6" fill="#0A0A0B"/>
+  <text font-family="'JetBrains Mono', ui-monospace, monospace" font-weight="700" font-size="25" dominant-baseline="middle"><tspan x="-6.50" y="17.28" fill="#FF2A3D">{</tspan><tspan x="8.50" y="17.28" fill="#fff">n</tspan><tspan x="23.50" y="17.28" fill="#FF2A3D">}</tspan></text>
+</svg>

package/assets/brand/nterminal-wordmark.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 243 34" width="243" height="34">
+  <text font-family="'JetBrains Mono', ui-monospace, monospace" font-weight="700" font-size="33"><tspan x="0.00" y="28.00" fill="#FF2A3D">{</tspan><tspan x="22.16" y="28.00" fill="#fff">n</tspan><tspan x="41.96" y="28.00" fill="#FF2A3D">·</tspan><tspan x="61.76" y="28.00" fill="#fff">terminal</tspan><tspan x="222.51" y="28.00" fill="#FF2A3D">}</tspan></text>
+</svg>

package/bin/nterminal.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const binDir = path.dirname(fileURLToPath(import.meta.url));
+const appDir = path.resolve(binDir, '..');
+const packageMode = !existsSync(path.join(appDir, '.git')) && !existsSync(path.join(appDir, 'src'));
+const userStateDir = path.join(os.homedir(), '.nterminal');
+
+const [command = 'help', ...args] = process.argv.slice(2);
+
+function defaultEnv() {
+  const env = {
+    ...process.env,
+    NTERMINAL_APP_DIR: process.env.NTERMINAL_APP_DIR ?? appDir
+  };
+  if (packageMode) {
+    env.NTERMINAL_ENV_FILE ??= path.join(userStateDir, '.env');
+    env.NTERMINAL_STATE_PATH ??= path.join(userStateDir, 'state.json');
+    env.NTERMINAL_PID_PATH ??= path.join(userStateDir, 'nterminal.pid');
+    env.NTERMINAL_LOG_PATH ??= path.join(userStateDir, 'nterminal.log');
+  }
+  return env;
+}
+
+function run(executable, runArgs) {
+  const result = spawnSync(executable, runArgs, {
+    cwd: appDir,
+    stdio: 'inherit',
+    env: defaultEnv()
+  });
+  process.exit(result.status ?? 1);
+}
+
+function runNode(modulePath, runArgs) {
+  run(process.execPath, [modulePath, ...runArgs]);
+}
+
+function runTypeScriptScript(scriptPath, runArgs) {
+  run(process.execPath, ['--import', 'tsx', scriptPath, ...runArgs]);
+}
+
+function scriptEntrypoint(name) {
+  const built = path.join(appDir, 'dist', 'scripts', `${name}.js`);
+  if (existsSync(built)) {
+    return { type: 'node', path: built };
+  }
+  const source = path.join(appDir, 'scripts', `${name}.ts`);
+  if (existsSync(source)) {
+    return { type: 'tsx', path: source };
+  }
+  return null;
+}
+
+function runScript(name, runArgs) {
+  const entrypoint = scriptEntrypoint(name);
+  if (!entrypoint) {
+    console.error(`error: ${name} entrypoint not found; run npm run build first`);
+    process.exit(1);
+  }
+  if (entrypoint.type === 'node') {
+    runNode(entrypoint.path, runArgs);
+  }
+  runTypeScriptScript(entrypoint.path, runArgs);
+}
+
+function runCtl(runArgs) {
+  run('bash', [path.join(appDir, 'scripts', 'nterminalctl'), ...runArgs]);
+}
+
+function printHelp() {
+  console.log(`Usage: nterminal <command>
+
+Commands:
+  onboarding              Run interactive main/secondary onboarding.
+  generate-secrets        Print a new NTERMINAL_SESSION_SECRET.
+  status                  Show process status.
+  start                   Start the built server.
+  stop                    Stop the managed server.
+  restart                 Restart the managed server.
+  build                   Build the app.
+  deploy                  npm install/ci, typecheck, build, then restart.
+  clean --force           Remove local runtime state.
+  logs [N]                Show recent logs.
+  logs -f [N]             Follow logs.
+  doctor                  Check local runtime readiness.
+  pid                     Print the running PID.
+  url                     Print the configured local URL.
+  help                    Show this help.
+`);
+}
+
+switch (command) {
+  case 'onboarding':
+    runScript('onboarding', args);
+    break;
+  case 'generate-secrets':
+  case 'generate:secrets':
+    runScript('generate-secrets', args);
+    break;
+  case 'ctl':
+    runCtl(args);
+    break;
+  case 'help':
+  case '-h':
+  case '--help':
+    printHelp();
+    break;
+  default:
+    runCtl([command, ...args]);
+}