M3.7: lutra CLI and single instance

- crates/control: rendezvous file (<data_dir>/instance.json, port + random
  token, atomic write, 0600 on Unix, stale detection), token-protected
  listener (start_with_token, app.auth first, constant-time compare,
  10 s auth timeout), app.focus, and a blocking client (connect_live,
  request/execute/subscribe/next_event, open_folder/open_file/reveal)
- lutra-desktop: a normal start forwards its path to a running instance
  and exits, otherwise claims the rendezvous; --control instances skip it
  unless LUTRA_RENDEZVOUS_DIR is set; non-Unicode args are usage errors
- lutra-cli (binary lutra, now L6): path[:line[:column]] targets, folder ->
  project.open, file -> file.open (parent opened without a project, outside
  the project refused), editor.reveal, starts the desktop if needed,
  --wait until bufferClosed, --version/--help, exit codes 0/1/2
- tests: proptest target parsing, rendezvous read/write/stale, token check
  over TCP, forwarding against a test backend, --wait end to end
- docs: architecture, G7, ROADMAP (agent automation 18% est.), roadmap,
  README

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-18 00:23:09 +02:00
parent 9ccfc1bf6a
commit 9b278099cf
26 changed files with 2162 additions and 37 deletions

View file

@ -0,0 +1,212 @@
//! The single instance over real sockets: the token check of the
//! rendezvous listener, stale rendezvous files, and forwarding a second
//! start's path to the running instance.
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::indexing_slicing)]
use std::io::{BufRead, BufReader, Write};
use std::net::TcpStream;
use std::path::Path;
use std::sync::Arc;
use std::time::Duration;
use lutra_control::client::{self, Client, Unavailable};
use lutra_control::rendezvous::{self, Instance};
use lutra_testkit::EngineBackend;
use serde_json::{Value, json};
const TIMEOUT: Duration = Duration::from_secs(10);
/// Starts a token listener for `backend` and writes its rendezvous file in
/// `dir`, as the desktop's claim does.
fn claim(dir: &Path, backend: Arc<EngineBackend>) -> Instance {
let token = rendezvous::new_token().unwrap();
let server = lutra_control::start_with_token(0, backend, &token).unwrap();
let instance = Instance {
port: server.local_addr().port(),
token,
pid: std::process::id(),
version: "test".into(),
};
rendezvous::write(dir, &instance).unwrap();
instance
}
/// Sends raw lines and reads one response line, or `None` at end of stream.
fn exchange(port: u16, lines: &[Value]) -> Vec<Option<Value>> {
let stream = TcpStream::connect(("127.0.0.1", port)).unwrap();
stream.set_read_timeout(Some(TIMEOUT)).unwrap();
let mut writer = stream.try_clone().unwrap();
let mut reader = BufReader::new(stream);
lines
.iter()
.map(|line| {
if writer.write_all(format!("{line}\n").as_bytes()).is_err() {
return None;
}
let mut text = String::new();
match reader.read_line(&mut text) {
Ok(0) | Err(_) => None,
Ok(_) => Some(serde_json::from_str(&text).unwrap()),
}
})
.collect()
}
#[test]
fn the_rendezvous_listener_needs_the_token_first() {
let dir = tempfile::tempdir().unwrap();
let instance = claim(dir.path(), Arc::new(EngineBackend::new()));
let ping = json!({"id": 2, "method": "app.ping"});
let r = exchange(instance.port, &[ping.clone(), ping.clone()]);
assert_eq!(r[0].as_ref().unwrap()["error"]["code"], "unauthorized");
assert!(r[1].is_none(), "the connection is closed");
let wrong = json!({"id": 1, "method": "app.auth", "params": {"token": "0".repeat(64)}});
let r = exchange(instance.port, &[wrong, ping.clone()]);
assert_eq!(r[0].as_ref().unwrap()["error"]["code"], "unauthorized");
assert!(r[1].is_none());
let r = exchange(instance.port, &[json!("garbage"), ping.clone()]);
assert_eq!(r[0].as_ref().unwrap()["error"]["code"], "unauthorized");
let right = json!({"id": 1, "method": "app.auth", "params": {"token": instance.token}});
let r = exchange(instance.port, &[right, ping]);
assert_eq!(r[0].as_ref().unwrap()["result"]["authenticated"], true);
assert_eq!(r[1].as_ref().unwrap()["result"]["pong"], true);
}
#[test]
fn the_open_control_channel_still_needs_no_token() {
let server = lutra_control::start(0, Arc::new(EngineBackend::new())).unwrap();
let mut client = Client::connect(server.local_addr().port(), TIMEOUT).unwrap();
assert_eq!(
client.request("app.ping", Value::Null).unwrap()["pong"],
true
);
}
#[test]
fn stale_files_are_detected() {
let dir = tempfile::tempdir().unwrap();
assert!(matches!(
client::connect_live(dir.path(), TIMEOUT),
Err(Unavailable::Missing)
));
std::fs::write(rendezvous::path(dir.path()), "{").unwrap();
assert!(matches!(
client::connect_live(dir.path(), TIMEOUT),
Err(Unavailable::Stale(_))
));
let closed = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let port = closed.local_addr().unwrap().port();
drop(closed);
let dead = Instance {
port,
token: "t".into(),
pid: 1,
version: "old".into(),
};
rendezvous::write(dir.path(), &dead).unwrap();
assert!(matches!(
client::connect_live(dir.path(), TIMEOUT),
Err(Unavailable::Stale(_))
));
let live = claim(dir.path(), Arc::new(EngineBackend::new()));
let reused = Instance {
token: "f".repeat(64),
..live.clone()
};
rendezvous::write(dir.path(), &reused).unwrap();
assert!(
matches!(
client::connect_live(dir.path(), TIMEOUT),
Err(Unavailable::Stale(_))
),
"a listener that refuses the token is not ours"
);
rendezvous::write(dir.path(), &live).unwrap();
let (found, _) = client::connect_live(dir.path(), TIMEOUT).unwrap();
assert_eq!(found, live, "the stale file was replaced");
}
#[test]
fn a_second_start_forwards_folders_and_files() {
let rv = tempfile::tempdir().unwrap();
let project = tempfile::tempdir().unwrap();
let other = tempfile::tempdir().unwrap();
let file = project.path().join("a.php");
std::fs::write(&file, "<?php\necho 1;\n").unwrap();
let outside = other.path().join("b.php");
std::fs::write(&outside, "<?php\n").unwrap();
let backend = Arc::new(EngineBackend::new());
claim(rv.path(), Arc::clone(&backend));
let (_, mut second) = client::connect_live(rv.path(), TIMEOUT).unwrap();
let opened = second.open_file(&file).unwrap();
assert_eq!(opened.path, "a.php");
let root = backend
.engine
.lock()
.unwrap()
.state()
.project
.as_ref()
.map(|w| w.project.root().to_path_buf());
assert!(root.is_some(), "the file's folder became the project");
let again = second.open_file(&file).unwrap();
assert_eq!(again.id, opened.id, "an open file is focused, not reopened");
let refused = second.open_file(&outside).unwrap_err();
assert_eq!(refused.code(), Some("failed"));
second.open_folder(other.path()).unwrap();
let opened = second.open_file(&outside).unwrap();
assert_eq!(opened.path, "b.php");
assert_eq!(
second.focus().unwrap_err().code(),
Some("focus_failed"),
"the test backend has no window"
);
}
#[test]
fn reveal_waits_for_the_window_and_sends_zero_based_positions() {
let rv = tempfile::tempdir().unwrap();
let project = tempfile::tempdir().unwrap();
let file = project.path().join("a.php");
std::fs::write(&file, "<?php\n").unwrap();
let backend = Arc::new(EngineBackend::new());
claim(rv.path(), Arc::clone(&backend));
let (_, mut client) = client::connect_live(rv.path(), TIMEOUT).unwrap();
let opened = client.open_file(&file).unwrap();
let early = client.reveal(&opened.path, 0, 0, Duration::from_millis(300));
assert_eq!(early.unwrap_err().code(), Some("unknown_command"));
client
.execute(
"ui.registerCommands",
json!({"commands": [{"id": "editor.reveal", "labelKey": "command.editor.reveal"}]}),
)
.unwrap();
client.subscribe().unwrap();
client.reveal(&opened.path, 9, 4, TIMEOUT).unwrap();
loop {
let event = client.next_event(Some(TIMEOUT)).unwrap().unwrap();
if event["kind"] == "uiCommand" {
assert_eq!(event["id"], "editor.reveal");
assert_eq!(
event["params"],
json!({"path": "a.php", "line": 9, "column": 4})
);
break;
}
}
}