@mmmbuto/nexuscrew 0.2.2 → 0.2.4

package/README.md

@@ -1,72 +1,73 @@
-## Overview
+# NexusCrew
 
-NexusCrew is a **tmux-based** AI cockpit that orchestrates Claude Code, Codex CLI, Gemini CLI, and Qwen Code through persistent tmux sessions.
+[![npm](https://img.shields.io/npm/v/@mmmbuto/nexuscrew?style=flat-square&logo=npm)](https://www.npmjs.org/package/@mmmbuto/nexuscrew)
 
-This is a **study project** exploring an alternative approach to AI CLI orchestration, based on experience with [NexusCLI](https://www.npmjs.com/package/@mmmbuto/nexuscli). Instead of managing PTY processes in-memory, NexusCrew delegates session lifecycle to **tmux** so sessions survive server restarts and can be accessed directly from the terminal.
+NexusCrew is a tmux-first AI cockpit for Claude Code, Codex CLI, Gemini CLI, and Qwen Code.
 
-> **Status**: Beta — experimental, API may change
-
-> **Disclaimer**: This project is experimental. The automation pipeline is fast enough that it may be generated, tested, and published before I finish thinking about it. Expect incomplete features, mistakes, and breaking changes.
+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.
 
 ---
 
-## Why tmux?
-
-| Problem | NexusCLI (PTY) | NexusCrew (tmux) |
-|---------|---------------|-------------------|
-| Server crash | All sessions die | Sessions survive |
-| Direct access | Web UI only | Web UI + `tmux attach` |
-| Remote machines | Not supported | Experimental host registry |
-| Native deps | node-pty required | SQLite native addon |
-| Session recovery | Manual | Automatic |
+## About
 
----
+- 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
 
-## Features
+## Project Scope
 
-- **Persistent sessions** — standalone tmux sessions survive server restarts
-- **Multi-engine** — Claude Code, Codex CLI, Gemini CLI, Qwen Code
-- **Auto-discovery** — detects installed CLIs plus live shell aliases/functions and generic shell config fallbacks
-- **Explicit tmux creation** — create a new tmux session only from a detected runnable launcher
-- **Unified web UI** — attach chat to real active tmux sessions
-- **SSE streaming** — real-time output from tmux sessions
-- **Cross-platform** — Linux, macOS, Termux (Android)
+### What It Does
 
----
+- 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
 
-## Engine Discovery
+### What It Does Not Do
 
-NexusCrew automatically detects:
+- 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
 
-1. **PATH binaries** — `claude`, `codex`, `gemini`, `qwen` when present in the runtime PATH
-2. **Live shell wrappers** — aliases/functions available in the current login shell
-3. **Shell-file fallbacks** — wrappers detected from `.zshrc`, `.bashrc`, `.profile`, and optional extra shell sources
+---
 
-Launchers detected only from shell files are shown as detected metadata but are not treated as runnable until they are verified in the active shell context.
+## Installation
 
----
+### Quick Start
 
-## Install
+Install:
 
 ```bash
 npm install -g @mmmbuto/nexuscrew
 ```
 
-Then initialize:
+Initialize local config:
 
 ```bash
 nexuscrew init
 ```
 
-And start:
+Start the server:
 
 ```bash
 nexuscrew start
 ```
 
-Open `http://localhost:41820` in your browser.
+Open:
+
+```text
+http://localhost:41820
+```
 
-### Termux (Android)
+### Termux Quick Start
 
 ```bash
 pkg install tmux nodejs
@@ -75,103 +76,126 @@ 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)
+
 ---
 
-## Hosts Registry
+## Runtime Model
 
-You can store SSH host definitions for later work:
+NexusCrew now works with standalone tmux sessions.
 
-```bash
-nexuscrew hosts add --name vps1 --host example.com --user user
-nexuscrew hosts add --name vps2 --host 192.168.1.10 --user admin --port 2222
-```
+That means:
 
-Host storage and connectivity tests are available, but the current UI and default session flow are local tmux-first. Treat remote execution as experimental until it is revalidated end-to-end.
+- 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
+```
 
 ---
 
-## Commands
+## Launcher Discovery
 
-| Command | Description |
-|---------|-------------|
-| `nexuscrew init` | First-time setup (config, hosts, tmux check) |
-| `nexuscrew start` | Start server |
-| `nexuscrew stop` | Stop server |
-| `nexuscrew status` | Server + tmux + hosts status |
-| `nexuscrew engines` | Discover available AI CLIs and aliases |
-| `nexuscrew sessions` | List tmux sessions |
-| `nexuscrew attach` | Attach to tmux session directly |
-| `nexuscrew config` | View/edit configuration |
-| `nexuscrew hosts list` | List configured hosts |
-| `nexuscrew hosts add` | Add remote SSH host |
-| `nexuscrew hosts remove` | Remove a host |
+Discovery is environment-agnostic and shell-agnostic.
 
----
+Sources, in order:
 
-## Configuration
+1. live shell introspection
+2. generic shell files such as `.zshrc`, `.bashrc`, `.profile`
+3. PATH binaries
 
-Config stored in `~/.nexuscrew/config.json`:
+Detection families are inferred from what is actually present, not from a static product catalog.
 
-```json
-{
-  "port": 41820,
-  "logDir": "~/.nexuscrew/logs",
-  "autoDiscovery": true,
-  "preferredShell": "",
-  "extraShellSources": []
-}
-```
+Current launcher families:
 
-Hosts stored in `~/.nexuscrew/hosts.json`:
+- `claude`
+- `codex`
+- `gemini`
+- `qwen`
+- `custom`
 
-```json
-[
-  { "name": "local", "type": "local", "default": true },
-  { "name": "vps1", "type": "ssh", "host": "example.com", "user": "user", "port": "22" }
-]
-```
+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
 
 ---
 
-## Network
+## Commands
 
-| Protocol | Default Port | Use Case |
-|----------|--------------|----------|
-| HTTP | `41820` | Local access |
+| 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 |
 
 ---
 
-## Architecture
+## Documentation
 
-```
-Browser ←SSE→ Express Server ←tmux→ active tmux sessions
-                                      ├─ session: claude-work
-                                      ├─ session: codex-debug
-                                      └─ session: qwen-sandbox
-```
+- [Installation Guide](docs/INSTALLATION.md)
+- [Configuration Guide](docs/CONFIGURATION.md)
+- [Current State](docs/CURRENT_STATE.md)
+- [Changelog](CHANGELOG.md)
+
+---
 
-Each AI session = one standalone tmux session. Output is piped to log files, parsed by the watcher, and streamed to the UI via SSE.
+## 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
 
 ```bash
-git clone https://github.com/dionanos/nexuscrew
+git clone https://github.com/DioNanos/nexuscrew
 cd nexuscrew
 npm install
-cd frontend && npm install && npm run build && cd ..
+npm run build
 npm run dev
 ```
 
 ---
 
-## Relation to NexusCLI
+## Known Gaps
 
-NexusCrew is a **study branch** inspired by [NexusCLI](https://www.npmjs.com/package/@mmmbuto/nexuscli). It shares the same web UI direction but replaces PTY-based process management with tmux-based persistent sessions. The goal is to explore whether tmux provides a simpler, more robust foundation for local AI CLI orchestration and crash recovery.
+- 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
 
 ---
 
 ## License
 
-MIT License. See [LICENSE](LICENSE).
+MIT. See `LICENSE`.

package/bin/nexuscrew.js

@@ -8,11 +8,13 @@ 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 = path.join(os.homedir(), '.nexuscrew');
-const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
-const HOSTS_PATH = path.join(CONFIG_DIR, 'hosts.json');
+const CONFIG_DIR = getConfigDir();
+const CONFIG_PATH = getConfigPath();
+const HOSTS_PATH = getHostsPath();
 
 const DEFAULT_PORT = '41820';
 
@@ -41,7 +43,7 @@ program.command('init')
     if (!fs.existsSync(CONFIG_PATH)) {
       fs.writeFileSync(CONFIG_PATH, JSON.stringify({
         port: Number(DEFAULT_PORT),
-        logDir: path.join(CONFIG_DIR, 'logs'),
+        logDir: getDefaultLogDir(),
         autoDiscovery: true,
         preferredShell: '',
         extraShellSources: []
@@ -56,7 +58,7 @@ program.command('init')
       log('Created hosts.json');
     }
 
-    const logDir = path.join(CONFIG_DIR, 'logs');
+    const logDir = getDefaultLogDir();
     if (!fs.existsSync(logDir)) {
       fs.mkdirSync(logDir, { recursive: true });
     }
@@ -241,13 +243,28 @@ hostsCmd.command('remove')
 
 program.command('engines')
   .description('Discover available launchers')
-  .action(() => {
-    const launchers = new EngineDiscovery(readConfig()).getLaunchers();
+  .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 launcher of launchers) {
-      console.log(`  ${launcher.label}: ${launcher.kind} [${launcher.family}]${launcher.runnable ? '' : ' (detected only)'}`);
-      console.log(`    command: ${launcher.commandPreview}`);
-      console.log(`    source:  ${launcher.source}`);
+    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('');
   });