@mmmbuto/nexuscrew 0.8.0 → 0.8.3

package/README.md

@@ -16,7 +16,7 @@ panes, windows. tmux does the work; the browser is just a faithful client.
 
 ---
 
-## What it is (v0.8 "Many Nodes, Many Monitors")
+## What it is (v0.8.3 "Simple and Clean")
 
 - 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
@@ -27,9 +27,9 @@ panes, windows. tmux does the work; the browser is just a faithful client.
 - **Multi-window decks**: named workspaces at `/deck/<name>` — one browser window per
   monitor, each with its own remembered tile layout. The focused tile is the size owner;
   everything else attaches with `ignore-size`.
-- **Multi-node**: register other hosts as nodes over dedicated restricted SSH tunnels and
-  see their tmux fleets in the same UI. Per-node groups, remote attach, and file exchange
-  all travel through a single-origin `/node/<name>` proxy using one local token.
+- **Multi-node**: connect existing NexusCrew installations through the SSH configuration you
+  already control and see their tmux fleets in the same UI. Per-node groups, remote attach,
+  file exchange, and Fleet management travel through a scoped single-origin route.
 - **Settings and wizard**: manage roles, nodes, token rotation, and service regeneration
   from the UI; a skippable first-run wizard guides initial setup.
 - **Session lifecycle from the UI**: create sessions (name + cwd + an allowlisted preset)
@@ -62,11 +62,19 @@ over a real PTY. On the right, a `codex-vl` session running inside the browser c
 ## Fleet integration
 
 A clean install includes the built-in, schema-driven fleet manager. Its safe defaults contain
-only two engine templates — **Claude Native** and **Codex-VL Native** — and no cells, prompts,
+three engine templates — **Claude Native**, **Codex Native**, and **Codex-VL Native** — and no cells, prompts,
 API keys, or machine-specific paths. Add cells and enable optional managed providers from the
-Fleet settings. Managed providers currently cover native login, Ollama Cloud Direct for Claude
-and Codex-VL, and Z.AI A/P for Claude. Provider secrets are read at launch from the 0600 file
-`~/.nexuscrew/providers.env`; API values are write-only and redacted from status and errors.
+Fleet settings. The managed matrix covers Claude Code, Codex, Codex-VL, and Pi with their
+documented native/local providers plus renameable custom providers. Custom Codex adapters are
+Responses-only. New custom credentials are read only from the environment variable named in
+the PWA; NexusCrew never stores the secret value. Existing Z.AI A/P and Ollama Cloud profiles
+retain their backwards-compatible credential loading.
+
+Managed engines expose a permission selector. New Claude engines (native, Z.AI, Ollama, or
+custom) default to **Bypass permissions** and launch with
+`--dangerously-skip-permissions`; choose **Standard permissions** to disable it. New Codex and
+Codex-VL engines default to Standard and offer an explicit opt-in for
+`--dangerously-bypass-approvals-and-sandbox`. Pi keeps its native permission behavior.
 
 Custom argv-based engines remain supported. Their command, environment, cwd, and prompt are
 validated against a strict trust boundary and launched without a shell.
@@ -111,35 +119,34 @@ channel you control**:
 ```bash
 # 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>
+# then run `nexuscrew show` on the machine where the browser is available
 ```
 
-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
+autossh reverse tunnels or a VPN work the same way. A local **authentication token** (0600 file,
+auto-generated and passed directly to the browser by `nexuscrew show`) 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.
 
 > **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".
 
-## Multi-node (one command, many nodes)
+## Federated Hydra nodes (configured from the PWA)
 
-Each installation can be a **client/hub**, a reachable **node**, or both. Add a host from
-the hub:
+Every installation is always the local node and can join other NexusCrew nodes. Open
+**Settings → Nodes**, create a ten-minute pairing link/QR on one device, then paste or scan it
+on the other together with an OpenSSH Host alias. That single pairing creates a reciprocal,
+loopback-only link and both sides exchange a redacted topology automatically.
 
-```bash
-nexuscrew nodes add vps --ssh user@host
-nexuscrew nodes test vps
-nexuscrew nodes up vps
-```
-
-NexusCrew creates a dedicated SSH key and prints the restricted `authorized_keys` entry.
-Every hop remains loopback → SSH → loopback: the app never binds a public interface and
-does not add its own TLS layer. The hub proxy injects the remote token only server-side;
-the browser sees one origin and authenticates with only the hub token. `nodes test`
-distinguishes tunnel-down, health failure, missing token, and rejected-token states.
+NexusCrew does not create SSH keys or edit `authorized_keys`. OpenSSH remains authoritative for
+identity files, agents, host keys, ports, ProxyJump and forwarding policy. NexusCrew uses
+`autossh` when available and otherwise its supervised `ssh`; configured links return at boot.
+Pair credentials are random, per-peer and scoped only to the federated session/file surface—the
+PWA token never crosses a peer link.
 
-For NAT-ed hosts such as phones, `nexuscrew node on` enables the reachable-node role using
-a reverse tunnel to a configured rendezvous host; `nexuscrew node off` disables it.
+A relay controls what its peers can see. The default is the whole network; a peer can be reduced
+to relay-only or a selected set. HTTP and WebSocket routing enforce that policy at every hop,
+with stable instance IDs, cycle rejection and a four-hop ceiling. Session creation, terminal,
+files, termination, and Fleet editing work on Local or any reachable route. Previously seen
+transitive nodes remain listed as offline with their last-seen time while a relay is down.
 
 ## Install & run
 
@@ -151,9 +158,9 @@ npm install -g @mmmbuto/nexuscrew
 nexuscrew
 ```
 
-The first run creates a loopback-only configuration and a `systemd --user` service when
-systemd is available. Linux x64 and ARM64 use platform PTY prebuilds; `node-pty` remains the
-build-from-source fallback.
+The first run creates a loopback-only configuration and starts a detached process. Run
+`nexuscrew boot` only if you want a persistent `systemd --user` service. Linux x64 and ARM64
+use platform PTY prebuilds; `node-pty` remains the build-from-source fallback.
 
 ### macOS (Apple Silicon or Intel)
 
@@ -163,9 +170,10 @@ npm install -g @mmmbuto/nexuscrew
 nexuscrew
 ```
 
-The first run installs a user LaunchAgent with an explicit Node/Homebrew PATH. The npm package
-selects the matching Darwin ARM64 or x64 PTY prebuild. NexusCrew is an npm/Node CLI, not an
-`.app`, `.pkg`, or standalone Mach-O distribution, so it does not require Developer ID signing.
+The first run starts a detached process. Run `nexuscrew boot` to install a user LaunchAgent
+with an explicit Node/Homebrew PATH. The npm package selects the matching Darwin ARM64 or x64
+PTY prebuild. NexusCrew is an npm/Node CLI, not an `.app`, `.pkg`, or standalone Mach-O
+distribution, so it does not require Developer ID signing.
 
 ### Android / Termux (ARM64)
 
@@ -176,18 +184,24 @@ npm install -g @mmmbuto/nexuscrew
 nexuscrew
 ```
 
-Termux uses the Android ARM64 PTY provider. Service startup uses a verified pidfile and a
-`~/.termux/boot/` script; install the Termux:Boot app only if you want automatic startup after
-reboot.
+Termux uses the Android ARM64 PTY provider. The normal command starts NexusCrew in the
+background and exits. `nexuscrew boot` installs the Termux:Boot script explicitly.
 
-On every platform, the command prints the local URL and an authenticated QR:
+On every platform the first run starts the server in the background and opens the PWA wizard.
+After onboarding, the same command starts or reuses it, prints a compact status and guide, and
+exits:
 
 ```bash
-nexuscrew                 # smart init/start; binds 127.0.0.1:41820
-nexuscrew url --qr        # print the authenticated URL again
+nexuscrew                 # background start; opens only on first run
+nexuscrew show            # background start when needed + open the authenticated PWA
+nexuscrew show token      # print the clickable authenticated URL; do not open a browser
+nexuscrew boot            # opt in to startup persistence
+nexuscrew boot off        # disable startup persistence, keep the current run alive
 ```
 
-Then tunnel in (see above) and open the printed URL with `#token=…`.
+The preferred port is `41820`. If it is occupied by another process, NexusCrew selects the
+next free loopback port and updates its configuration. If the configured port already hosts
+the same authenticated NexusCrew instance, it is reused.
 
 Env knobs: `NEXUSCREW_PORT` (default 41820), `NEXUSCREW_CONFIG_FILE`,
 `NEXUSCREW_TOKEN_FILE`, `NEXUSCREW_FILES_ROOT`, `NEXUSCREW_TMUX`,
@@ -197,25 +211,18 @@ resolved PTY provider at startup.
 ## CLI
 
 ```
-nexuscrew                    smart-up: init (zero questions) if needed → start → URL + QR
-nexuscrew start | up         start the service (systemd --user / launchd / nohup+pidfile)
-nexuscrew stop | down        stop the service (service manager / verified pidfile)
-nexuscrew status [--json]    platform, service, port, url, roles (client/node), nodes
-nexuscrew url [--qr]         reprint the full URL with #token (+ scannable QR) — token shown ONLY here
-nexuscrew token rotate       atomically rotate the token + restart to invalidate live sessions
-nexuscrew logs [-f]          journalctl --user -u nexuscrew (linux) / logfile (mac, termux); -f follows
-nexuscrew doctor             self-check: node, tmux, PTY, service, boot, token perms (exit 1 on problems)
-nexuscrew mcp                stdio MCP server for AI sessions (notify / ask / send file / status)
-nexuscrew update             npm i -g @mmmbuto/nexuscrew@latest + restart if active
-nexuscrew init [--port N]    explicit setup (detect + config + token + service)
-nexuscrew nodes add <name> --ssh user@host [--remote-port N] [--key path]
-nexuscrew nodes list | remove <name> | test <name> | up|down|restart <name> | set-token <name>
-nexuscrew node on|off        reachable-node role (reverse tunnel to a rendezvous)
+nexuscrew          background start; first run opens the PWA wizard
+nexuscrew show     start when needed and open the authenticated PWA
+nexuscrew show token  print the clickable authenticated URL without opening it
+nexuscrew boot     enable startup at boot (`boot off|status` are also available)
+nexuscrew doctor   local diagnostics (exit 1 when a required check fails)
+nexuscrew help     concise command help
+nexuscrew version  installed version
 ```
 
-The token is **never** printed by `status`, `logs`, `smart-up` or any service output — it appears
-only in `nexuscrew url` (and, embedded, in the QR). `nexuscrew url --qr` is the killer feature on
-Termux: scan it with the phone to open the tunnelled URL already authenticated.
+All configuration and lifecycle operations live in the PWA. Internal service-manager and MCP
+entry points are intentionally not part of the public CLI workflow. The token is never printed
+by normal startup, help, doctor, or service output.
 
 ## MCP bridge
 
@@ -273,13 +280,12 @@ holding.** On a screen smaller than the session you'll see a clipped view (expec
 ```bash
 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
+node bin/nexuscrew.js serve
 ```
 
 ## Status
 
-v0.8.0 is the current release on both **`latest`** and **`next`**, including Linux,
-macOS, and Android/Termux support.
+The current stable release is **v0.8.3**, published on npm under the **`latest`** dist-tag.
 
 ## License
 

package/bin/nexuscrew.js

@@ -1,7 +1,13 @@
 #!/usr/bin/env node
 'use strict';
-// NexusCrew CLI dispatcher (portable). Subcomandi: init / serve / start / stop / status.
+// The normal product surface is the PWA. `nexuscrew` starts it in background;
+// `nexuscrew show` starts it when needed and opens it.
 const { dispatch } = require('../lib/cli/commands.js');
-const r = dispatch(process.argv.slice(2));
-// serve tiene il processo vivo (server.listen); gli altri comandi escono.
-if (!r || !r.keepAlive) process.exit((r && r.code) || 0);
+Promise.resolve(dispatch(process.argv.slice(2)))
+  .then((r) => {
+    if (!r || !r.keepAlive) process.exitCode = (r && r.code) || 0;
+  })
+  .catch((e) => {
+    process.stderr.write(`nexuscrew: ${String((e && e.message) || e)}\n`);
+    process.exitCode = 1;
+  });