zwire_host/
lib.rs

1//! `zwire-host` — one small self-contained binary that exposes the local
2//! machine to any app over a JSON message protocol.
3//!
4//! Originally the Chrome native-messaging host for the [`zwire`] HUD, it is now a
5//! **universal local endpoint**: system stats, a namespaced key/value store, a
6//! filesystem crawler, subprocess exec, clipboard/notify/open, and multiplexed
7//! PTY terminals — reachable from a browser extension *and* from tmux, emacs,
8//! desktop apps, plugins, and any language.
9//!
10//! # Transports
11//! * **Native messaging** (default): `u32`-length-prefixed JSON on stdio, for
12//!   Chrome. Just run the binary with no recognised subcommand.
13//! * **Socket daemon**: `zwire-host serve` listens on a Unix socket speaking
14//!   newline-delimited JSON — the lingua franca every tool already has.
15//! * **Client**: `zwire-host call '{"cmd":"hostinfo"}'` sends one request and
16//!   prints the reply frames.
17//!
18//! Both transports feed the same [`session::Session`] dispatcher, so every
19//! capability is reachable from every client.
20//!
21//! [`zwire`]: https://github.com/MenkeTechnologies/zwire
22pub mod api;
23pub mod bus;
24pub mod exec;
25pub mod fsops;
26pub mod hostlog;
27pub mod jobs;
28pub mod osops;
29pub mod peer;
30#[cfg(feature = "sysinfo-caps")]
31pub mod procs;
32pub mod proto;
33#[cfg(feature = "pty")]
34pub mod pty;
35pub mod session;
36pub mod store;
37#[cfg(feature = "sysinfo-caps")]
38pub mod sysmon;
39#[cfg(feature = "tauri")]
40pub mod tauri_theme;
41pub mod theme_watch;
42pub mod transport;
43pub mod watch;
44
45// Re-export the handful of types a dependent binary needs to embed the host.
46// This lets sibling hosts (e.g. `zpwrchrome-host`) pull this crate in and reuse
47// the dispatcher + transports directly:
48//
49// ```no_run
50// // in another crate's main.rs, with `zwire-host` as a dependency:
51// fn main() {
52//     // zero-config: full native-messaging + `serve`/`call` behaviour
53//     zwire_host::run(std::env::args().skip(1).collect());
54// }
55// ```
56//
57// Or drive the dispatcher yourself over any transport:
58//
59// ```no_run
60// use zwire_host::{Peer, Session};
61// let out = Peer::ndjson(Box::new(std::io::stdout()));
62// let mut sess = Session::new();
63// sess.handle(&out, &serde_json::json!({"cmd": "hostinfo"}));
64// ```
65pub use proto::{Framing, Out, Peer};
66pub use session::{caps, Session};
67
68use std::io::Read;
69use std::path::PathBuf;
70
71/// Crate version, surfaced in `hello`/`hostinfo` replies.
72pub const VERSION: &str = env!("CARGO_PKG_VERSION");
73
74/// Where the socket daemon listens by default. `$ZWIRE_HOST_SOCK` overrides on
75/// every platform. Otherwise:
76///   * Windows — a per-user named pipe `\\.\pipe\zwire-host-<user>`.
77///   * Unix — a *runtime* dir, never the persistent state dir: Linux
78///     `$XDG_RUNTIME_DIR/zwire-host.sock`, macOS `$TMPDIR/zwire-host.sock`
79///     (the per-user `/var/folders/…/T`, mode 0700), else `/tmp`.
80///
81/// A socket is ephemeral runtime state, so it deliberately does not live under
82/// the app-data/state dir the scheme + kv files use.
83///
84/// On Windows the returned path's *leaf* is used as the pipe's namespaced name;
85/// the directory portion is ignored.
86pub fn default_socket() -> PathBuf {
87    if let Ok(p) = std::env::var("ZWIRE_HOST_SOCK") {
88        return PathBuf::from(p);
89    }
90    #[cfg(windows)]
91    {
92        let user = std::env::var("USERNAME").unwrap_or_else(|_| "user".into());
93        let safe: String = user
94            .chars()
95            .filter(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_'))
96            .collect();
97        let name = if safe.is_empty() { "user".into() } else { safe };
98        PathBuf::from(format!("zwire-host-{name}"))
99    }
100    #[cfg(not(windows))]
101    {
102        // Linux: the XDG runtime dir (/run/user/<uid>, mode 0700).
103        if let Ok(rt) = std::env::var("XDG_RUNTIME_DIR") {
104            if !rt.is_empty() {
105                return PathBuf::from(rt).join("zwire-host.sock");
106            }
107        }
108        // macOS: TMPDIR is the per-user Darwin temp dir (/var/folders/…/T, mode
109        // 0700) — the moral equivalent of XDG_RUNTIME_DIR, and short enough to
110        // stay under the 104-byte sun_path limit.
111        if let Ok(tmp) = std::env::var("TMPDIR") {
112            if !tmp.is_empty() {
113                return PathBuf::from(tmp).join("zwire-host.sock");
114            }
115        }
116        // Last resort: a per-user name in the world-shared /tmp. The daemon binds
117        // 0600 and clears a stale file first, so a foreign owner just fails bind.
118        let user = std::env::var("USER").unwrap_or_else(|_| "user".into());
119        let safe: String = user
120            .chars()
121            .filter(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_'))
122            .collect();
123        let user = if safe.is_empty() { "user".into() } else { safe };
124        PathBuf::from("/tmp").join(format!("zwire-host-{user}.sock"))
125    }
126}
127
128/// Cyberpunk `--help` wordmark (ANSI-Shadow "ZWIRE-HOST"), cyan→magenta→red.
129const BANNER: &str = concat!(
130    "\x1b[36m███████╗██╗    ██╗██╗██████╗ ███████╗    ██╗  ██╗ ██████╗ ███████╗████████╗\x1b[0m\n",
131    "\x1b[36m╚══███╔╝██║    ██║██║██╔══██╗██╔════╝    ██║  ██║██╔═══██╗██╔════╝╚══██╔══╝\x1b[0m\n",
132    "\x1b[35m  ███╔╝ ██║ █╗ ██║██║██████╔╝█████╗█████╗███████║██║   ██║███████╗   ██║   \x1b[0m\n",
133    "\x1b[35m ███╔╝  ██║███╗██║██║██╔══██╗██╔══╝╚════╝██╔══██║██║   ██║╚════██║   ██║   \x1b[0m\n",
134    "\x1b[31m███████╗╚███╔███╔╝██║██║  ██║███████╗    ██║  ██║╚██████╔╝███████║   ██║   \x1b[0m\n",
135    "\x1b[31m╚══════╝ ╚══╝╚══╝ ╚═╝╚═╝  ╚═╝╚══════╝    ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝   \x1b[0m\n",
136);
137
138/// Static body of the `--help` screen (a plain string literal, so the JSON
139/// braces in the EXAMPLES section stay literal).
140const HELP_BODY: &str = "  \x1b[35m>> UNIVERSAL LOCAL HOST // FULL SPECTRUM <<\x1b[0m\n\n  universal local host — system stats · fs · exec · pty · kv · os\n\n\x1b[33m  USAGE:\x1b[0m zwire-host [MODE] [OPTIONS]\n\n\x1b[36m  ── MODES ─────────────────────────────────────────────────────\x1b[0m\n  zwire-host                     \x1b[32m//\x1b[0m native-messaging on stdio (Chrome default)\n  zwire-host serve               \x1b[32m//\x1b[0m run the NDJSON socket daemon\n  zwire-host call '<json>'       \x1b[32m//\x1b[0m send one request to the daemon, print reply\n  zwire-host call                \x1b[32m//\x1b[0m ...reading the request JSON from stdin\n  zwire-host call --stream '...' \x1b[32m//\x1b[0m keep printing frames (sysinfo/pty streams)\n  zwire-host version | help      \x1b[32m//\x1b[0m print version / this help\n\n\x1b[36m  ── OPTIONS ───────────────────────────────────────────────────\x1b[0m\n  -s, --socket <path>            \x1b[32m//\x1b[0m socket ($ZWIRE_HOST_SOCK / $XDG_RUNTIME_DIR / $TMPDIR)\n  -f, --stream                   \x1b[32m//\x1b[0m relay every reply frame instead of just the first\n      --tcp <addr>               \x1b[32m//\x1b[0m (serve) also listen for peers/remote clients on TCP\n      --token <tok>              \x1b[32m//\x1b[0m (serve) shared secret required of inbound TCP\n      --name <name>              \x1b[32m//\x1b[0m (serve) advertised peer name (default: hostname)\n      --peer <addr>              \x1b[32m//\x1b[0m (serve) dial a peer and keep it linked; repeatable\n  -h, --help                     \x1b[32m//\x1b[0m print this help\n  -V, --version                  \x1b[32m//\x1b[0m print version\n\n\x1b[36m  ── EXAMPLES ──────────────────────────────────────────────────\x1b[0m\n  zwire-host serve &\n  zwire-host call '{\"cmd\":\"hostinfo\"}'\n  zwire-host call '{\"cmd\":\"fs_walk\",\"path\":\"~/src\",\"ext\":\"rs\"}'\n  echo '{\"cmd\":\"exec\",\"program\":\"git\",\"args\":[\"status\"]}' | zwire-host call\n  zwire-host call --stream '{\"cmd\":\"sysinfo_start\"}'\n  zwire-host serve --tcp 0.0.0.0:7420 --token SECRET --peer other.local:7420\n";
141
142/// Build the styled `--help` / `-h` screen in the MenkeTechnologies house
143/// style (see `tp -h`): banner, a status box padded at runtime so its right
144/// border never drifts as VERSION grows, cyan section rules, green `//`.
145fn usage() -> String {
146    const BOX_W: usize = 72;
147    let status = format!(" STATUS: ONLINE  // SIGNAL: ████████░░ // v{VERSION}");
148    let space = " ".repeat(BOX_W.saturating_sub(status.chars().count()));
149    let rule = "─".repeat(BOX_W);
150    format!(
151        "\n{BANNER} \x1b[36m┌{rule}┐\x1b[0m\n \x1b[36m│\x1b[0m{status}{space}\x1b[36m│\x1b[0m\n \x1b[36m└{rule}┘\x1b[0m\n{HELP_BODY}\n\x1b[36m  ── SYSTEM ────────────────────────────────────────────────────\x1b[0m\n  \x1b[35mv{VERSION} \x1b[0m// \x1b[33m(c) MenkeTechnologies\x1b[0m\n  \x1b[35mOne pipe. One binary. The whole machine.\x1b[0m\n  \x1b[33m>>> JACK IN. ONE SOCKET. OWN YOUR MACHINE. <<<\x1b[0m\n \x1b[36m░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░\x1b[0m\n"
152    )
153}
154
155/// Entry point: interpret `args` (everything after `argv[0]`) and run the chosen
156/// transport. Any unrecognised first token falls through to native-messaging
157/// mode, because Chrome launches the host with extension-origin arguments we
158/// must ignore.
159pub fn run(args: Vec<String>) {
160    // Pull optional flags out of the arg list.
161    let mut socket = default_socket();
162    let mut follow = false;
163    let mut tcp: Option<String> = None;
164    let mut token: Option<String> = None;
165    let mut name: Option<String> = None;
166    let mut peers: Vec<String> = Vec::new();
167    let mut positional: Vec<String> = Vec::new();
168    let mut it = args.into_iter();
169    while let Some(a) = it.next() {
170        match a.as_str() {
171            "--socket" | "-s" => {
172                if let Some(p) = it.next() {
173                    socket = PathBuf::from(p);
174                }
175            }
176            "--stream" | "--follow" | "-f" => follow = true,
177            "--tcp" => tcp = it.next(),
178            "--token" => token = it.next(),
179            "--name" => name = it.next(),
180            "--peer" => {
181                if let Some(p) = it.next() {
182                    peers.push(p);
183                }
184            }
185            _ => positional.push(a),
186        }
187    }
188
189    match positional.first().map(String::as_str) {
190        Some("serve") => transport::serve(transport::ServeConfig {
191            socket,
192            tcp,
193            token,
194            name,
195            peers,
196        }),
197        Some("call") => {
198            let rest = positional[1..].join(" ");
199            let request = if rest.trim().is_empty() {
200                let mut s = String::new();
201                let _ = std::io::stdin().read_to_string(&mut s);
202                s
203            } else {
204                rest
205            };
206            transport::call(&socket, &request, follow);
207        }
208        Some("version") | Some("--version") | Some("-V") => {
209            println!("zwire-host {VERSION}");
210        }
211        Some("help") | Some("--help") | Some("-h") => {
212            print!("{}", usage());
213        }
214        // `stdio`, no args, or Chrome's origin argument → native messaging.
215        _ => transport::stdio(),
216    }
217}
zwire_host/lib.rs

zwire_host/
lib.rs
