@mmmbuto/nexuscrew 0.2.5 → 0.4.1

package/README.md

@@ -1,201 +1,101 @@
 # NexusCrew
 
-[![npm](https://img.shields.io/npm/v/@mmmbuto/nexuscrew?style=flat-square&logo=npm)](https://www.npmjs.org/package/@mmmbuto/nexuscrew)
+[![npm (next)](https://img.shields.io/npm/v/@mmmbuto/nexuscrew/next?style=flat-square&logo=npm&label=npm%40next&color=cb3837)](https://www.npmjs.com/package/@mmmbuto/nexuscrew)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
+[![platforms](https://img.shields.io/badge/platforms-linux%20%C2%B7%20macos%20%C2%B7%20android-555?style=flat-square)](#requirements)
+[![bind](https://img.shields.io/badge/bind-127.0.0.1%20only-success?style=flat-square)](#access-model--read-this)
 
-NexusCrew is a tmux-first AI cockpit for Claude Code, Codex CLI, Gemini CLI, and Qwen Code.
+A faithful **browser tmux client**. It attaches to your live tmux sessions over a **real PTY**
+and streams them to a mobile-friendly web UI — full color, copy-mode scroll, special keys,
+panes, windows. tmux does the work; the browser is just a faithful client.
 
-It is built around one core rule: chat targets real tmux sessions that already exist, or new tmux sessions that are created explicitly from launchers detected on the current machine.
+> **NexusCrew does not create, own, or recover sessions — it only attaches.**
 
 ---
 
-## About
+## What it is (v0.4 "pty-core")
 
-- Runtime model: active tmux sessions + explicit tmux creation
-- Launcher discovery: runtime-driven, shell-agnostic, user-agnostic
-- Primary verified environment: Termux on Android
-- Linux/macOS: supported by design, not yet fully revalidated in the current cycle
-- Remote hosts: registry and connectivity exist, but end-to-end remote session flow is still experimental
+- Runs a small server on the host where your tmux sessions live.
+- Each attach spawns a real PTY running `tmux attach` and bridges its bytes over a WebSocket
+  to [xterm.js](https://xtermjs.org) in the browser. **No screenshots, no polling.**
+- **localhost-only**: the server binds `127.0.0.1` and refuses any non-loopback bind.
+- **Stateless**: tmux *is* the persistence. No database, no accounts.
+- **Universal**: a PTY is a PTY — a coding agent, a REPL, a plain shell, anything tmux holds.
 
-## Project Scope
+## Requirements
 
-### What It Does
+- **Node.js ≥ 18**
+- **tmux** on the host (3.4+; the non-destructive `ignore-size` attach is honored on 3.4 and
+  later)
+- A PTY backend is resolved automatically per platform: `node-pty` (Linux/macOS),
+  `@lydell/node-pty-linux-x64` (prebuilt Linux x64), and the native arm64 provider on Android/Termux.
 
-- Lists real active tmux sessions on the host
-- Lets the UI attach chat to an existing tmux session
-- Detects runnable launchers from:
-  - PATH binaries
-  - live shell aliases/functions
-  - generic shell config fallbacks
-- Creates a new standalone tmux session only when you explicitly ask for it
-- Stores conversation state locally in SQLite
-- Streams output back through SSE
+## Access model — read this
 
-### What It Does Not Do
-
-- It does not create hidden tmux master sessions
-- It does not keep a hardcoded list of AI models or wrappers
-- It does not assume a user-specific home like `/home/dag`
-- It does not treat shell-file-only detections as runnable unless the active shell confirms them
-
----
-
-## Installation
-
-### Quick Start
-
-Install:
+NexusCrew binds **only to `127.0.0.1`**. There is no built-in network exposure, no public
+tunnel, no TLS, no login server. You reach it by **bringing the loopback port to you over a
+channel you control**:
 
 ```bash
-npm install -g @mmmbuto/nexuscrew
+# from your laptop/phone, tunnel the loopback port over SSH
+ssh -L 41820:127.0.0.1:41820 user@your-host
+# then open http://localhost:41820/#token=<token printed by the server>
 ```
 
-Initialize local config:
+autossh reverse tunnels or a VPN work the same way. A short-lived **local token** (0600 file,
+auto-generated, printed once at startup) is a second factor on top of your SSH/VPN gate. The
+token travels in the URL **fragment** (`#token=…`), so it never reaches the server logs.
 
-```bash
-nexuscrew init
-```
+> **Exposing the app publicly (reverse proxy, network bind, port forward to the internet) is
+> unsupported and unsafe.** The whole security model is "localhost + a tunnel you control".
 
-Start the server:
+## Install & run
 
 ```bash
-nexuscrew start
-```
-
-Open:
-
-```text
-http://localhost:41820
-```
-
-### Termux Quick Start
-
-```bash
-pkg install tmux nodejs
-npm install -g @mmmbuto/nexuscrew
-nexuscrew init
-nexuscrew start
-```
-
-Notes:
-
-- the package uses a Termux-compatible SQLite dependency path during install
-- detailed install notes live in [docs/INSTALLATION.md](docs/INSTALLATION.md)
-
----
-
-## Runtime Model
-
-NexusCrew now works with standalone tmux sessions.
-
-That means:
+# install the test channel
+npm install -g @mmmbuto/nexuscrew@next
 
-- one AI runtime = one tmux session
-- chat sends to an existing tmux session
-- new tmux sessions are created explicitly from a detected launcher
-- session output is piped to log files and watched by the server
-
-Architecture:
-
-```text
-Browser <--SSE--> Express server <--tmux--> active tmux sessions
-                                           |- claude-work
-                                           |- codex-debug
-                                           `- qwen-sandbox
+nexuscrew                 # prints the URL + token, binds 127.0.0.1:41820
 ```
 
----
-
-## Launcher Discovery
-
-Discovery is environment-agnostic and shell-agnostic.
-
-Sources, in order:
+Then tunnel in (see above) and open the printed URL with `#token=…`.
 
-1. live shell introspection
-2. generic shell files such as `.zshrc`, `.bashrc`, `.profile`
-3. PATH binaries
+Env knobs: `NEXUSCREW_PORT` (default 41820), `NEXUSCREW_TOKEN_FILE`, `NEXUSCREW_TMUX`,
+`NEXUSCREW_READONLY=1`. Set `NEXUSCREW_DEBUG=1` to log the resolved PTY provider at startup.
 
-Detection families are inferred from what is actually present, not from a static product catalog.
+## Mobile KeyBar
 
-Current launcher families:
+The awkward tmux gestures, as buttons: **scroll** (enters copy-mode; then PgUp/↑/↓, `q` to
+exit), **window** prev/next, **pane** left/right, **esc**, **Ctrl-C**, **detach**.
 
-- `claude`
-- `codex`
-- `gemini`
-- `qwen`
-- `custom`
+Window and pane navigation run as **server-side, allowlisted tmux commands** on the active
+session — they are *not* emulated with client-side prefix keys, which are fragile and depend
+on each host's key bindings.
 
-Important distinction:
-
-- `runnable: true` means the launcher is valid for explicit tmux creation now
-- `runnable: false` means it was detected from shell config metadata only
-
----
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `nexuscrew init` | Create config, hosts file, and logs directory |
-| `nexuscrew start` | Start the web server |
-| `nexuscrew stop` | Stop the server |
-| `nexuscrew status` | Show server, tmux, and host status |
-| `nexuscrew sessions` | List active tmux sessions |
-| `nexuscrew attach -s <name>` | Attach to a tmux session directly |
-| `nexuscrew engines` | Print discovered launchers |
-| `nexuscrew config --list` | Show config |
-| `nexuscrew config --set key=value` | Update config |
-| `nexuscrew hosts list` | List stored hosts |
-| `nexuscrew hosts add ...` | Add an SSH host entry |
-| `nexuscrew hosts remove ...` | Remove an SSH host entry |
-
----
+## Non-destructive by default (`ignore-size`)
 
-## Documentation
+Multiple clients on one tmux session share the window geometry. To avoid a small phone
+shrinking the window for the real terminal you also have attached, NexusCrew attaches with
+`-f ignore-size` by default: **the browser never resizes a session that a real terminal is
+holding.** On a screen smaller than the session you'll see a clipped view (expected). Pass
+`takeSize` only when you deliberately want the browser to drive the size.
 
-- [Installation Guide](docs/INSTALLATION.md)
-- [Configuration Guide](docs/CONFIGURATION.md)
-- [Current State](docs/CURRENT_STATE.md)
-- [Changelog](CHANGELOG.md)
-
----
-
-## Support Matrix
-
-| Area | State |
-|------|----------------|
-| Local tmux session listing | Verified |
-| Explicit local tmux creation | Verified |
-| Runtime launcher discovery | Verified |
-| Bucketed launcher discovery | Verified |
-| Shell-file-only launcher gating | Verified |
-| Host-scoped tmux/session selection | Implemented |
-| SSE send flow | Improved, basic smoke tested |
-| Interrupt flow | Improved, not deeply stress-tested |
-| Remote host registry | Present |
-| Remote host execution | Implemented, pending live smoke |
-
----
-
-## Development
+## Develop
 
 ```bash
-git clone https://github.com/DioNanos/nexuscrew
-cd nexuscrew
-npm install
-npm run build
-npm run dev
+npm test            # node --test (config, tmux list, pty attach smoke, ws bridge, token)
+npm run build       # builds the frontend into frontend/dist
+node bin/nexuscrew.js
 ```
 
----
-
-## Known Gaps
+## Status
 
-- remote tmux workflows still need live multi-host smoke before being advertised as stable
-- send/interrupt should still be stress-tested against long-running CLI pauses
-
----
+v0.4 "pty-core" is published on the **`next`** dist-tag for install-and-try on real devices
+(Android/Termux included). The `latest` tag is reserved for a verified stable release.
 
 ## License
 
-MIT. See `LICENSE`.
+MIT © DioNanos
+
+*Per aspera ad astra.*

package/bin/nexuscrew.js

@@ -1,298 +1,3 @@
 #!/usr/bin/env node
 'use strict';
-
-const { Command } = require('commander');
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-const { execSync, spawn } = require('child_process');
-
-const EngineDiscovery = require('../lib/services/engine-discovery');
-const TmuxManager = require('../lib/services/tmux-manager');
-const { getConfigDir, getConfigPath, getHostsPath, getDefaultLogDir } = require('../lib/config/paths');
-const packageJson = require('../package.json');
-
-const CONFIG_DIR = getConfigDir();
-const CONFIG_PATH = getConfigPath();
-const HOSTS_PATH = getHostsPath();
-
-const DEFAULT_PORT = '41820';
-
-const program = new Command();
-program
-  .name('nexuscrew')
-  .description('tmux-based AI cockpit')
-  .version(packageJson.version);
-
-program.command('init')
-  .description('First-time setup')
-  .option('--silent', 'Suppress setup output')
-  .action((opts) => {
-    const log = (...args) => {
-      if (!opts.silent) console.log(...args);
-    };
-    const error = (...args) => {
-      if (!opts.silent) console.error(...args);
-    };
-
-    if (!fs.existsSync(CONFIG_DIR)) {
-      fs.mkdirSync(CONFIG_DIR, { recursive: true });
-      log('Created ~/.nexuscrew/');
-    }
-
-    if (!fs.existsSync(CONFIG_PATH)) {
-      fs.writeFileSync(CONFIG_PATH, JSON.stringify({
-        port: Number(DEFAULT_PORT),
-        logDir: getDefaultLogDir(),
-        autoDiscovery: true,
-        preferredShell: '',
-        extraShellSources: []
-      }, null, 2));
-      log('Created config.json');
-    }
-
-    if (!fs.existsSync(HOSTS_PATH)) {
-      fs.writeFileSync(HOSTS_PATH, JSON.stringify([
-        { name: 'local', type: 'local', default: true }
-      ], null, 2));
-      log('Created hosts.json');
-    }
-
-    const logDir = getDefaultLogDir();
-    if (!fs.existsSync(logDir)) {
-      fs.mkdirSync(logDir, { recursive: true });
-    }
-
-    try {
-      execSync('command -v tmux >/dev/null 2>&1', { stdio: 'pipe' });
-      log('tmux: OK');
-    } catch {
-      error('tmux not found! Install: apt install tmux (or pkg install tmux)');
-    }
-
-    log('\nDone! Run: nexuscrew start');
-  });
-
-program.command('start')
-  .description('Start the server')
-  .option('-p, --port <port>', 'Port', DEFAULT_PORT)
-  .option('-d, --dev', 'Dev mode (no frontend)')
-  .action((opts) => {
-    const env = { ...process.env, PORT: opts.port };
-    if (opts.dev) env.NEXUSCREW_DEV = '1';
-
-    const args = [path.join(__dirname, '..', 'lib', 'server', 'server.js')];
-    const child = spawn('node', args, {
-      env,
-      stdio: 'inherit',
-      detached: false
-    });
-    child.on('exit', (code) => process.exit(code || 0));
-  });
-
-program.command('stop')
-  .description('Stop the server')
-  .action(() => {
-    try {
-      const pid = execSync(`lsof -ti :${DEFAULT_PORT} 2>/dev/null`).toString().trim();
-      if (pid) {
-        execSync(`kill ${pid}`);
-        console.log('Server stopped');
-      } else {
-        console.log('Server not running');
-      }
-    } catch {
-      console.log('Server not running');
-    }
-  });
-
-program.command('status')
-  .description('Show server and tmux status')
-  .action(() => {
-    console.log('=== NexusCrew Status ===\n');
-
-    try {
-      const pid = execSync(`lsof -ti :${DEFAULT_PORT} 2>/dev/null`).toString().trim();
-      console.log(`Server: RUNNING (pid ${pid})`);
-    } catch {
-      console.log('Server: STOPPED');
-    }
-
-    try {
-      const sessions = execSync("tmux list-sessions -F '#{session_name} #{?session_attached,*, }' 2>/dev/null").toString().trim();
-      console.log('\nActive tmux sessions:');
-      sessions.split('\n').filter(Boolean).forEach((session) => console.log(`  ${session}`));
-    } catch {
-      console.log('\nActive tmux sessions: none');
-    }
-
-    if (fs.existsSync(HOSTS_PATH)) {
-      const hosts = JSON.parse(fs.readFileSync(HOSTS_PATH, 'utf8'));
-      console.log('\nHosts:');
-      hosts.forEach((host) => {
-        if (host.type === 'local') {
-          console.log(`  ${host.name}: local`);
-        } else {
-          const status = testSSH(host) ? 'OK' : 'UNREACHABLE';
-          console.log(`  ${host.name}: ${host.user}@${host.host}${host.port ? ':' + host.port : ''} [${status}]`);
-        }
-      });
-    }
-  });
-
-program.command('attach')
-  .description('Attach to a tmux session')
-  .requiredOption('-s, --session <name>', 'Session name')
-  .action((opts) => {
-    try {
-      execSync(`tmux attach -t ${shellQuote(opts.session)}`, { stdio: 'inherit' });
-    } catch {
-      console.error(`Session not found: ${opts.session}`);
-    }
-  });
-
-program.command('sessions')
-  .description('List active tmux sessions')
-  .action(() => {
-    try {
-      const out = execSync(
-        "tmux list-sessions -F '#{session_name} [#{session_windows} windows] #{?session_attached,(attached),}' 2>/dev/null"
-      ).toString().trim();
-      console.log(out || 'No tmux sessions found');
-    } catch {
-      console.log('No tmux sessions found');
-    }
-  });
-
-program.command('config')
-  .description('View/edit configuration')
-  .option('-l, --list', 'Show current config')
-  .option('-s, --set <key=value>', 'Set a config value')
-  .action((opts) => {
-    if (!fs.existsSync(CONFIG_PATH)) {
-      console.error('Run nexuscrew init first');
-      return;
-    }
-    const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
-
-    if (opts.set) {
-      const [key, ...rest] = opts.set.split('=');
-      const value = rest.join('=');
-      let parsedValue = value;
-      if (value === 'true') parsedValue = true;
-      if (value === 'false') parsedValue = false;
-      if (!Number.isNaN(Number(value)) && value.trim() !== '') parsedValue = Number(value);
-      config[key] = parsedValue;
-      fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
-      console.log(`Set ${key} = ${value}`);
-    } else {
-      console.log(JSON.stringify(config, null, 2));
-    }
-  });
-
-const hostsCmd = program.command('hosts').description('Manage remote hosts');
-
-hostsCmd.command('list')
-  .description('List configured hosts')
-  .action(() => {
-    if (!fs.existsSync(HOSTS_PATH)) {
-      console.log('No hosts configured. Run nexuscrew init.');
-      return;
-    }
-    const hosts = JSON.parse(fs.readFileSync(HOSTS_PATH, 'utf8'));
-    hosts.forEach((host, i) => {
-      const status = host.type === 'local' ? 'local' : (testSSH(host) ? 'OK' : 'UNREACHABLE');
-      console.log(`[${i}] ${host.name} (${host.type}) ${host.host || ''} [${status}]${host.default ? ' *default*' : ''}`);
-    });
-  });
-
-hostsCmd.command('add')
-  .description('Add a remote host')
-  .requiredOption('-n, --name <name>', 'Host name')
-  .requiredOption('-h, --host <host>', 'Hostname or IP')
-  .option('-u, --user <user>', 'SSH user', os.userInfo().username)
-  .option('-p, --port <port>', 'SSH port', '22')
-  .option('-k, --key <path>', 'SSH key path')
-  .action((opts) => {
-    const hosts = fs.existsSync(HOSTS_PATH)
-      ? JSON.parse(fs.readFileSync(HOSTS_PATH, 'utf8'))
-      : [];
-    hosts.push({
-      name: opts.name,
-      type: 'ssh',
-      host: opts.host,
-      user: opts.user,
-      port: opts.port,
-      key: opts.key || undefined
-    });
-    fs.writeFileSync(HOSTS_PATH, JSON.stringify(hosts, null, 2));
-    console.log(`Added host: ${opts.name}`);
-  });
-
-hostsCmd.command('remove')
-  .description('Remove a host')
-  .requiredOption('-n, --name <name>', 'Host name')
-  .action((opts) => {
-    let hosts = fs.existsSync(HOSTS_PATH)
-      ? JSON.parse(fs.readFileSync(HOSTS_PATH, 'utf8'))
-      : [];
-    hosts = hosts.filter((host) => host.name !== opts.name);
-    fs.writeFileSync(HOSTS_PATH, JSON.stringify(hosts, null, 2));
-    console.log(`Removed host: ${opts.name}`);
-  });
-
-program.command('engines')
-  .description('Discover available launchers')
-  .option('-H, --host <name>', 'Host name', 'local')
-  .action((opts) => {
-    const config = readConfig();
-    const hosts = fs.existsSync(HOSTS_PATH)
-      ? JSON.parse(fs.readFileSync(HOSTS_PATH, 'utf8'))
-      : [{ name: 'local', type: 'local', default: true }];
-    const tmux = new TmuxManager({
-      configDir: CONFIG_DIR,
-      logDir: config.logDir || getDefaultLogDir(),
-      preferredShell: config.preferredShell || process.env.SHELL || '/bin/sh',
-      hosts
-    });
-    const launchers = new EngineDiscovery({ ...config, tmux }).discover(opts.host || 'local');
-    console.log('\nDiscovered Launchers:\n');
-    for (const [bucket, items] of Object.entries(launchers.buckets)) {
-      if (items.length === 0) continue;
-      console.log(`  ${bucket}:`);
-      for (const launcher of items) {
-        console.log(`    ${launcher.label}: ${launcher.kind} [${launcher.family}]${launcher.runnable ? '' : ' (detected only)'}`);
-        console.log(`      command: ${launcher.commandPreview}`);
-        console.log(`      source:  ${launcher.source}`);
-      }
-    }
-    console.log('');
-  });
-
-function readConfig() {
-  if (!fs.existsSync(CONFIG_PATH)) {
-    return { preferredShell: '', extraShellSources: [] };
-  }
-  const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
-  if (config.providersPath && !config.extraShellSources) {
-    config.extraShellSources = [config.providersPath].filter(Boolean);
-  }
-  return config;
-}
-
-function testSSH(host) {
-  try {
-    const keyOpt = host.key ? `-i ${shellQuote(host.key)}` : '';
-    const portOpt = host.port && host.port !== '22' ? `-p ${host.port}` : '';
-    execSync(`ssh -o ConnectTimeout=3 -o BatchMode=yes ${keyOpt} ${portOpt} ${host.user}@${host.host} echo ok`, { stdio: 'pipe' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function shellQuote(value) {
-  return `'${String(value).replace(/'/g, `'\\''`)}'`;
-}
-
-program.parse();
+require('../lib/server.js').start();