Initial public release

Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
This commit is contained in:
Evan Whittaker
2026-10-17 12:08:30 -05:00
commit 09a7de2520
1730 changed files with 412952 additions and 0 deletions

View File

@@ -0,0 +1,473 @@
//! Guide check — the user guide's config examples, flags and slash commands, held against the code.
//!
//! `docs/guide/` is what a user copies from and what an agent follows. Luxe ignores a config key it
//! does not know, on purpose, so an old config loads on a new Luxe; the cost is that a misspelled
//! or invented key in the docs loads too, and does nothing. These tests load every example the
//! guide names a file for as that file, and fail on anything Luxe would ignore.
//!
//! A code block opts in by naming its file in the fence, ` ```json title="config.json" `, which is
//! also what the site shows above the block. `scripts/docs-check.py` covers links and voice.
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use clap::CommandFactory;
use serde::de::DeserializeOwned;
use crate::cli::Args;
fn guide_dir() -> PathBuf {
Path::new(env!("CARGO_MANIFEST_DIR")).join("../../docs/guide")
}
/// Every page, as `(name, text)`.
fn pages() -> Vec<(String, String)> {
let mut pages: Vec<(String, String)> = std::fs::read_dir(guide_dir())
.expect("docs/guide exists beside the crates")
.filter_map(Result::ok)
.map(|entry| entry.path())
.filter(|path| path.extension().is_some_and(|ext| ext == "md"))
.map(|path| {
let name = path.file_stem().unwrap_or_default().to_string_lossy().into_owned();
let text = std::fs::read_to_string(&path).expect("a guide page reads as UTF-8");
(name, text)
})
.collect();
pages.sort();
pages
}
/// A fenced code block.
struct Block {
/// Where it starts, as `page.md:line`
at: String,
lang: String,
/// The file it says it is, from `title="…"` in the fence
title: Option<String>,
body: String,
}
fn blocks(page: &str, text: &str) -> Vec<Block> {
let mut blocks = Vec::new();
let mut open: Option<(usize, String, Option<String>, Vec<&str>)> = None;
for (number, line) in text.lines().enumerate() {
match (&mut open, line.trim_start().strip_prefix("```")) {
(None, Some(info)) => {
let lang = info.split_whitespace().next().unwrap_or_default().to_owned();
let title = info
.split_once("title=\"")
.and_then(|(_, rest)| rest.split_once('"'))
.map(|(title, _)| title.to_owned());
open = Some((number + 1, lang, title, Vec::new()));
}
(Some(_), Some(_)) => {
let (start, lang, title, lines) = open.take().expect("a block is open");
blocks.push(Block {
at: format!("{page}.md:{start}"),
lang,
title,
body: lines.join("\n"),
});
}
(Some((_, _, _, lines)), None) => lines.push(line),
(None, None) => {}
}
}
blocks
}
/// The keys Luxe would ignore reading `text` as `T`, as paths like `dock.mode`.
fn ignored<T: DeserializeOwned>(text: &str) -> Result<Vec<String>, String> {
let value: serde_json::Value = serde_json::from_str(text).map_err(|error| error.to_string())?;
let mut paths = Vec::new();
serde_ignored::deserialize::<_, _, T>(value, |path| paths.push(path.to_string()))
.map_err(|error| error.to_string())?;
Ok(paths)
}
/// The keys Luxe would ignore in an `auth.json`: every top-level key is a provider's credential,
/// except the configuration keys it shares with `models.json`.
fn auth_file(text: &str) -> Result<Vec<String>, String> {
const CONFIGURATION: &[&str] =
&["providers", "models", "default_provider", "default_model", "$schema"];
let value: serde_json::Value = serde_json::from_str(text).map_err(|error| error.to_string())?;
let object = value.as_object().ok_or("auth.json is an object")?;
let (configuration, credentials): (serde_json::Map<_, _>, serde_json::Map<_, _>) =
object.clone().into_iter().partition(|(key, _)| CONFIGURATION.contains(&key.as_str()));
let mut unknown = ignored::<luxe_providers::config::ModelsConfig>(
&serde_json::Value::Object(configuration).to_string(),
)?;
unknown.extend(
credentials
.iter()
.filter(|(_, entry)| luxe_providers::auth::Credential::from_json(entry).is_none())
.map(|(provider, _)| format!("{provider} (not a credential)")),
);
Ok(unknown)
}
/// What is wrong with `text` as the file `title` names, if anything.
fn check_file(title: &str, text: &str) -> Result<(), String> {
let file = title.rsplit('/').next().unwrap_or(title);
let unknown = match file {
"config.json" => ignored::<luxe_core::config::Config>(text)?,
"models.json" => ignored::<luxe_providers::config::ModelsConfig>(text)?,
"auth.json" => auth_file(text)?,
"permissions.json" => ignored::<luxe_core::permission::PermissionsFile>(text)?,
"hooks.json" => {
let mut unknown = ignored::<luxe_core::command_hooks::HooksFile>(text)?;
let file = luxe_core::command_hooks::HooksFile::from_json(text)
.map_err(|error| error.to_string())?;
unknown.extend(
file.unknown_points.into_iter().map(|point| format!("{point} (hook point)")),
);
unknown
}
"mcp.json" | ".mcp.json" if text.contains("\"mcpServers\"") => {
ignored::<luxe_core::mcp_config::StandardConfigFile>(text)?
}
"mcp.json" | ".mcp.json" => ignored::<luxe_core::mcp_config::McpConfigFile>(text)?,
"keybindings.json" => {
let map: HashMap<String, Vec<String>> =
serde_json::from_str(text).map_err(|error| error.to_string())?;
let mut unknown = Vec::new();
for (action, chords) in map {
if luxe_core::keymap::UiAction::from_id(&action).is_none() {
unknown.push(format!("{action} (action)"));
}
for chord in chords {
if luxe_core::keymap::KeyChord::parse(&chord).is_err() {
unknown.push(format!("{chord} (chord, for {action})"));
}
}
}
unknown
}
"lsp-servers.json" => ignored::<HashMap<String, luxe_lsp::ServerEntryPatch>>(text)?,
"debug-adapters.json" => ignored::<Vec<luxe_dap::CustomAdapter>>(text)?,
_ if title.contains("themes/") && file.ends_with(".json") => {
ignored::<luxe_core::theme::Theme>(text)?
}
_ => return Err(format!("no file type known for {title}; add it to `check_file`")),
};
if unknown.is_empty() {
Ok(())
} else {
Err(format!("Luxe would ignore {}", unknown.join(", ")))
}
}
/// Every config example the guide names a file for loads as that file, with nothing ignored.
#[test]
fn every_named_config_example_loads() {
let mut failures = Vec::new();
for (page, text) in pages() {
for block in blocks(&page, &text) {
let Some(title) = block.title.as_deref() else { continue };
if block.lang != "json" {
continue;
}
if let Err(problem) = check_file(title, &block.body) {
failures.push(format!("{} ({title}): {problem}", block.at));
}
}
}
assert!(
failures.is_empty(),
"config examples Luxe would not read as written:\n{}",
failures.join("\n")
);
}
/// The command lines the guide shows: `luxe …` at the start of a shell line or an inline code span.
fn command_lines(page: &str, text: &str) -> Vec<(String, String)> {
let mut found = Vec::new();
for block in blocks(page, text) {
if !matches!(block.lang.as_str(), "bash" | "sh" | "shell" | "console" | "") {
continue;
}
for line in block.body.lines() {
let line = line.trim().trim_start_matches("$ ");
if line == "luxe" || line.starts_with("luxe ") {
found.push((block.at.clone(), line.to_owned()));
}
}
}
for (number, line) in text.lines().enumerate() {
for span in line.split('`').skip(1).step_by(2) {
if span == "luxe" || span.starts_with("luxe ") {
found.push((format!("{page}.md:{}", number + 1), span.to_owned()));
}
}
}
found
}
/// `line` split the way a shell would split it: a quoted argument is one word.
fn shell_words(line: &str) -> Vec<String> {
let mut words = Vec::new();
let mut word = String::new();
let mut quote: Option<char> = None;
let mut in_word = false;
for c in line.chars() {
match (quote, c) {
(Some(open), c) if c == open => quote = None,
(Some(_), c) => word.push(c),
(None, '"' | '\'') => {
quote = Some(c);
in_word = true;
}
(None, c) if c.is_whitespace() => {
if in_word {
words.push(std::mem::take(&mut word));
in_word = false;
}
}
(None, c) => {
word.push(c);
in_word = true;
}
}
}
if in_word {
words.push(word);
}
words
}
/// What is wrong with a `luxe …` command line, if anything: a flag or subcommand Luxe lacks.
fn check_command_line(root: &clap::Command, line: &str) -> Result<(), String> {
let mut path: Vec<&clap::Command> = vec![root];
let words = shell_words(line);
let mut tokens = words.iter().map(String::as_str).skip(1).peekable();
while let Some(token) = tokens.next() {
if matches!(token, "#" | "|" | "||" | "&&" | ";" | ">" | "<" | "2>&1" | "\\") {
break;
}
let here = *path.last().expect("the root is always on the path");
let flag = |arg: &clap::Arg| {
if let Some(long) = token.strip_prefix("--") {
let long = long.split('=').next().unwrap_or(long);
arg.get_long() == Some(long)
|| arg.get_all_aliases().is_some_and(|aliases| aliases.contains(&long))
} else {
token.len() == 2 && arg.get_short() == token.chars().nth(1)
}
};
if token.starts_with('-') && token.len() > 1 {
// a global flag is declared once, on an ancestor
let arg =
path.iter().rev().find_map(|command| command.get_arguments().find(|arg| flag(arg)));
let Some(arg) = arg else {
let name =
path.iter().map(|command| command.get_name()).collect::<Vec<_>>().join(" ");
return Err(format!("`{name}` has no {token}"));
};
if arg.get_action().takes_values() && !token.contains('=') {
tokens.next();
}
} else if let Some(sub) = here.find_subcommand(token) {
path.push(sub);
}
}
Ok(())
}
/// Every `luxe` flag and subcommand the guide shows exists.
#[test]
fn every_command_line_in_the_guide_exists() {
let mut root = Args::command();
root.build();
let mut failures = Vec::new();
for (page, text) in pages() {
for (at, line) in command_lines(&page, &text) {
if let Err(problem) = check_command_line(&root, &line) {
failures.push(format!("{at}: {problem}: {line}"));
}
}
}
assert!(failures.is_empty(), "command lines Luxe would refuse:\n{}", failures.join("\n"));
}
/// Paths that look like a slash command in a code span.
const NOT_COMMANDS: &[&str] =
&["/tmp", "/etc", "/usr", "/dev", "/home", "/var", "/opt", "/bin", "/proc"];
/// Every slash command the guide names is one Luxe has.
#[test]
fn every_slash_command_in_the_guide_exists() {
let registry = luxe_tui::commands::CommandRegistry::all();
let mut failures = Vec::new();
for (page, text) in pages() {
let mut in_code = false;
for (number, line) in text.lines().enumerate() {
if line.trim_start().starts_with("```") {
in_code = !in_code;
continue;
}
if in_code {
continue;
}
for span in line.split('`').skip(1).step_by(2) {
let name = span.split_whitespace().next().unwrap_or_default();
let looks_like_one = name.len() > 1
&& name.starts_with('/')
&& name[1..]
.chars()
.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-');
// an API version in a URL path, `/v1`
let version = name.len() > 2
&& name.starts_with("/v")
&& name[2..].chars().all(|c| c.is_ascii_digit());
if looks_like_one
&& !version
&& !NOT_COMMANDS.contains(&name)
&& registry.parse_slash(span).is_none()
{
failures.push(format!("{page}.md:{}: {span}", number + 1));
}
}
}
}
assert!(failures.is_empty(), "slash commands Luxe does not have:\n{}", failures.join("\n"));
}
/// The command reference lists every slash command Luxe has, and every key it binds by default, so a
/// new command or binding cannot ship undocumented.
#[test]
fn the_command_reference_is_complete() {
let page = std::fs::read_to_string(guide_dir().join("commands.md")).expect("commands.md");
let mut missing: Vec<String> = luxe_tui::commands::CommandRegistry::all()
.iter()
.filter_map(|command| command.slash_name().map(str::to_owned))
.filter(|slash| {
!page.contains(&format!("`{slash}`")) && !page.contains(&format!("`{slash} "))
})
.collect();
let defaults = luxe_core::keymap::KeyMap::defaults().to_config_map();
missing.extend(defaults.into_keys().filter(|action| !page.contains(&format!("`{action}`"))));
missing.sort();
assert!(missing.is_empty(), "commands.md does not mention:\n{}", missing.join("\n"));
}
/// The configuration reference names every key `config.json` takes, from the schema Luxe writes
/// beside it, so a new setting cannot ship undocumented.
#[test]
fn the_configuration_reference_is_complete() {
fn keys(node: &serde_json::Value, prefix: &str, out: &mut Vec<String>) {
let Some(properties) = node.get("properties").and_then(serde_json::Value::as_object) else {
return;
};
for (name, child) in properties {
if name == "$schema" {
continue;
}
let path = format!("{prefix}{name}");
// a block is documented by its keys, not by a row of its own
if child.get("properties").is_some() {
keys(child, &format!("{path}."), out);
} else {
out.push(path);
}
}
}
let schema: serde_json::Value =
serde_json::from_str(luxe_core::config::Config::schema_json()).expect("the schema parses");
let page =
std::fs::read_to_string(guide_dir().join("configuration.md")).expect("configuration.md");
let mut all = Vec::new();
keys(&schema, "", &mut all);
// siblings may be listed by their leaf: `plan.model`, `.thinking`
let missing: Vec<String> = all
.into_iter()
.filter(|key| {
let leaf = key.rsplit('.').next().unwrap_or(key);
!page.contains(&format!("`{key}`")) && !page.contains(&format!("`.{leaf}`"))
})
.collect();
assert!(missing.is_empty(), "configuration.md does not mention:\n{}", missing.join("\n"));
}
/// The RPC reference lists every action a client may send, from the protocol's own published list.
#[test]
fn the_rpc_reference_lists_every_action() {
let page = std::fs::read_to_string(guide_dir().join("rpc.md")).expect("rpc.md");
let missing: Vec<&str> = luxe_core::event::Action::KINDS
.iter()
.copied()
.filter(|kind| !page.contains(&format!("| `{kind}` |")))
.collect();
assert!(missing.is_empty(), "rpc.md has no row for: {missing:?}");
let version = format!("`protocol_version` is `{}`", luxe_core::event::PROTOCOL_VERSION);
assert!(page.contains(&version), "rpc.md names a different protocol version");
}
/// The command-line reference names every subcommand and flag the CLI has, so neither can ship
/// undocumented.
#[test]
fn the_command_line_reference_is_complete() {
fn walk(command: &clap::Command, path: &str, page: &str, missing: &mut Vec<String>) {
for arg in command.get_arguments() {
let Some(long) = arg.get_long() else { continue };
if matches!(long, "help" | "version") || arg.is_hide_set() {
continue;
}
if !page.contains(&format!("--{long}")) {
missing.push(format!("{path} --{long}"));
}
}
for sub in command.get_subcommands() {
if sub.get_name() == "help" || sub.is_hide_set() {
continue;
}
let path = format!("{path} {}", sub.get_name());
if !page.contains(&format!("`{path}")) && !page.contains(&format!(", `{path}")) {
missing.push(path.clone());
}
walk(sub, &path, page, missing);
}
}
let page = std::fs::read_to_string(guide_dir().join("cli.md")).expect("cli.md");
let mut root = Args::command();
root.build();
let mut missing = Vec::new();
walk(&root, "luxe", &page, &mut missing);
missing.dedup();
assert!(missing.is_empty(), "cli.md does not mention:\n{}", missing.join("\n"));
}
/// The checks themselves can fail: an invented key, flag and command are each caught.
#[test]
fn the_checks_catch_what_they_exist_for() {
assert!(check_file("~/.config/luxe/config.json", r#"{ "dock": { "mode": "auto" } }"#).is_ok());
let problem = check_file("config.json", r#"{ "dock": { "moed": "auto" } }"#).unwrap_err();
assert!(problem.contains("dock.moed"), "{problem}");
assert!(
check_file("hooks.json", r#"{ "pre_tool_usage": [] }"#).is_err(),
"an unknown hook point"
);
assert!(check_file("keybindings.json", r#"{ "tui.nope": ["ctrl+x"] }"#).is_err());
assert!(check_file("notes.json", "{}").is_err(), "a file nobody taught it");
assert!(
check_file("auth.json", r#"{ "openai": { "type": "api_key", "key": "sk-x" } }"#).is_ok()
);
assert!(check_file("auth.json", r#"{ "openai": { "kind": "nope" } }"#).is_err());
assert!(check_file("auth.json", r#"{ "providers": { "x": { "base_urll": "y" } } }"#).is_err());
let mut root = Args::command();
root.build();
assert!(check_command_line(&root, "luxe --headless -p \"hi\"").is_ok());
assert!(check_command_line(&root, "luxe auth login anthropic").is_ok());
assert!(check_command_line(&root, "luxe --model gpt-5 --no-such-flag").is_err());
assert!(check_command_line(&root, "luxe auth login --stdin < key.txt").is_ok());
assert!(
check_command_line(&root, "luxe mcp add --id c --name \"C\" --command \"npx -y x\"")
.is_ok(),
"a quoted argument is one word"
);
assert!(check_command_line(&root, "luxe mcp add --id c --nope \"a b\"").is_err());
let registry = luxe_tui::commands::CommandRegistry::all();
assert!(registry.parse_slash("/model").is_some());
assert!(registry.parse_slash("/no-such-command").is_none());
}