Breadway/bread
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add rules.toml: declarative event->action automation without Lua

Browse source 
Adds a bread.rules built-in module plus a breadd/src/core/rules.rs
parser/validator so the common "when event X happens, do Y" case
(dock connect script, AC-disconnect notification, keyboard rate on
connect) no longer requires hand-written init.lua.

- rules.toml is optional, XDG_CONFIG_HOME-aware (mirrors breadd.toml's
  config_path() resolution), and purely additive alongside init.lua.
- Each [[rule]] needs `on` (event suffix, "bread." implied, wildcards
  supported) and exactly one of run/exec/notify. `run` names a single
  script (tilde-expanded + shell-quoted so spaces in the path can't be
  word-split); `exec` is a raw shell command line passed through as-is;
  `notify` shows a desktop notification.
- Rule data is threaded into the bread.rules Lua module via globals
  set just before it loads (same technique load_profiles() already
  uses for __profiles_path), avoiding any need to hand-escape values
  into generated Lua source text.
- Parse/validation failures surface through the existing module
  load-error path (Lua error() -> run_on_load -> set_module_status),
  so a bad rules.toml shows up via `bread doctor` exactly like a
  broken hand-written module would, without blocking other valid
  rules in the same file.
- Documentation.md gets a new Getting-started fast path plus a
  Dictionary entry; README's Configuration section gets a short
  pointer. Since: v1.5.
This commit is contained in:
Breadway 2026-08-04 22:05:26 +08:00
parent 96639516b1
commit 45b5aee117
7 changed files with 904 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

83
Documentation.md
View file

@ -48,10 +48,56 @@ This matters because the moment sibling apps and community modules depend on thi
### 1) Create a minimal config
- Daemon config: `~/.config/bread/breadd.toml` (all values optional)
- Declarative rules (optional, no Lua required): `~/.config/bread/rules.toml`
- Lua entry point: `~/.config/bread/init.lua`
- Lua modules: `~/.config/bread/modules/`
### 2) Minimal `init.lua`
### 2) The fast path: `rules.toml` *(Since: v1.5)*
For the common "when event X happens, do Y" case, you don't need Lua at
all. Create `~/.config/bread/rules.toml`:
```toml
[[rule]]
on = "device.dock.connected"
run = "~/.config/bread/scripts/dock-connected.sh"
[[rule]]
on = "power.ac.disconnected"
notify = "Unplugged"
[[rule]]
on = "device.keyboard.connected"
exec = "xset r rate 200 40"
```
Each `[[rule]]` needs exactly two things: an `on` (an event-name suffix —
`bread.` is implied, so `"device.dock.connected"` matches the real event
`bread.device.dock.connected`; wildcards `*`/`**`/`?` work the same way they
do in `bread.on()`) and exactly one action:
| Action | Meaning |
|--------|---------|
| `run = "<path>"` | Run exactly one script/program at that path. The path is tilde-expanded and quoted as a single unit for you, so spaces in it are safe — it will *not* be word-split into a command plus arguments. |
| `exec = "<command line>"` | Run a full shell command line via `bread.exec()`, exactly as if you'd typed it in a shell — quote/escape arguments yourself. |
| `notify = "<message>"` | Show a desktop notification with this text via `bread.notify()`. |
`rules.toml` is entirely optional and purely additive alongside
`init.lua` — both can coexist, rules load before user-defined modules, and
an absent file is not an error. A malformed rule (missing/empty `on`, or
zero/multiple action keys set) doesn't stop the rest of the file from
working: the other rules in the file still register, and the specific bad
rule shows up via `bread doctor` (see [Debugging tips](#debugging-tips))
the same way a broken Lua module's error would.
This covers the common cases directly. For fuzzier matching (substring
device-name matching, filtering by a list of monitors, etc.) or any logic
beyond "run this one action," reach for `bread.devices` /
`bread.monitors` or hand-written Lua in `init.lua` — see
[Dictionary: Built-in modules](#dictionary-built-in-modules) and the next
section.
### 3) Minimal `init.lua`
```lua
bread.on("bread.system.startup", function(event)
@ -60,7 +106,7 @@ bread.on("bread.system.startup", function(event)
end)
```
### 3) Start the daemon
### 4) Start the daemon
```bash
systemctl --user start breadd
@ -69,7 +115,7 @@ systemctl --user start breadd
breadd
```
### 4) Check that it's running
### 5) Check that it's running
```bash
bread ping
@ -673,6 +719,37 @@ Storage is scoped per module and is not shared across modules.
Built-ins are loaded before user modules. Disable them via `[modules].disable` in the daemon config.
### `bread.rules` *(Since: v1.5)*
The Lua side of the `rules.toml` declarative automation layer described in
[Getting started](#getting-started) — there is no separate API to call
here, it's driven entirely by `~/.config/bread/rules.toml`. Listed here (and
disable-able via `[modules].disable = ["bread.rules"]` like every other
built-in) because it's a real module the same way `bread.devices` is, just
one whose configuration lives in TOML instead of Lua.
```toml
# ~/.config/bread/rules.toml
[[rule]]
on = "device.dock.connected"
run = "~/.config/bread/scripts/dock-connected.sh"
[[rule]]
on = "power.ac.disconnected"
notify = "Unplugged"
[[rule]]
on = "device.keyboard.connected"
exec = "xset r rate 200 40"
```
Each rule's `on` becomes a `bread.on("bread." .. on, ...)` subscription —
see [Getting started](#getting-started) for the full `run`/`exec`/`notify`
semantics and validation rules. `rules.toml`'s absence is not an error;
parse/validation problems are reported the same way a broken hand-written
module's `on_load` error would be — via `bread doctor` / `modules.list`,
against the `bread.rules` module name.
### `bread.monitors`
High-level declarative monitor event handlers.

26
README.md
View file

@ -150,11 +150,33 @@ default_urgency = "normal"
notify_send_path = "notify-send"
[modules]
builtin = true # load built-in modules (monitors, devices, workspaces, binds)
builtin = true # load built-in modules (monitors, devices, workspaces, binds, rules)
disable = [] # list of built-in module names to disable
```
Your automation lives in `~/.config/bread/init.lua`. Modules placed in `~/.config/bread/modules/` are auto-loaded after `init.lua`:
For the common "when event X happens, do Y" case, you don't need Lua at
all — drop rules straight into `~/.config/bread/rules.toml` and skip
`init.lua` entirely:
```toml
# ~/.config/bread/rules.toml
[[rule]]
on = "device.dock.connected"
run = "~/.config/bread/scripts/dock-connected.sh"
[[rule]]
on = "power.ac.disconnected"
notify = "Unplugged"
```
It's optional and purely additive alongside `init.lua` — see
[Getting started in Documentation.md](Documentation.md#getting-started) for
the full schema (`run` vs `exec` vs `notify`, wildcard `on` patterns, and
how a malformed rule surfaces via `bread doctor`).
For anything beyond a single action per event, your automation lives in
`~/.config/bread/init.lua`. Modules placed in `~/.config/bread/modules/` are
auto-loaded after `init.lua`:
```lua
-- ~/.config/bread/init.lua

36
breadd/src/core/config.rs
View file

@ -256,6 +256,19 @@ fn config_path() -> PathBuf {
expand_home("~/.config/bread/breadd.toml")
}
/// Location of the optional `rules.toml` — declarative automation rules
/// (see `crate::core::rules`). Resolved with the exact same
/// `XDG_CONFIG_HOME`-vs-`HOME` precedence as `config_path()` above; see the
/// `expand_home` doc comment for why every config-adjacent path the daemon
/// resolves has to agree on that precedence.
pub fn rules_path() -> PathBuf {
if let Ok(xdg) = env::var("XDG_CONFIG_HOME") {
return Path::new(&xdg).join("bread").join("rules.toml");
}
expand_home("~/.config/bread/rules.toml")
}
/// Expands a leading `~/`. `~/.config/...` paths specifically prefer
/// `$XDG_CONFIG_HOME` when it's set, consistent with `config_path()`'s own
/// resolution of `breadd.toml` itself — otherwise the default `lua.entry_point`
@ -264,7 +277,7 @@ fn config_path() -> PathBuf {
/// though the config file that sets them was found via that same variable,
/// which is exactly the kind of inconsistency that made init.lua/module
/// loading silently no-op for a XDG_CONFIG_HOME-only test setup.
fn expand_home(input: &str) -> PathBuf {
pub(crate) fn expand_home(input: &str) -> PathBuf {
if let Some(stripped) = input.strip_prefix("~/.config/") {
if let Ok(xdg_config) = env::var("XDG_CONFIG_HOME") {
return Path::new(&xdg_config).join(stripped);
@ -586,4 +599,25 @@ log_level = "trace"
PathBuf::from("/synthetic/home/.config/bread/breadd.toml")
);
}
#[test]
fn rules_path_respects_xdg_config_home() {
let _g = EnvGuard::new(&["XDG_CONFIG_HOME", "HOME"]);
std::env::set_var("XDG_CONFIG_HOME", "/synthetic/xdg-config");
assert_eq!(
rules_path(),
PathBuf::from("/synthetic/xdg-config/bread/rules.toml")
);
}
#[test]
fn rules_path_falls_back_to_home_when_no_xdg() {
let _g = EnvGuard::new(&["XDG_CONFIG_HOME", "HOME"]);
std::env::remove_var("XDG_CONFIG_HOME");
std::env::set_var("HOME", "/synthetic/home");
assert_eq!(
rules_path(),
PathBuf::from("/synthetic/home/.config/bread/rules.toml")
);
}
}

1
breadd/src/core/mod.rs
View file

@ -1,5 +1,6 @@
pub mod config;
pub mod normalizer;
pub mod rules;
pub mod state_engine;
pub mod subscriptions;
pub mod supervisor;

410
breadd/src/core/rules.rs Normal file
View file

@ -0,0 +1,410 @@
//! `rules.toml` — a declarative shortcut for the common "when event X
//! happens, do Y" case that otherwise requires hand-written Lua
//! (`bread.on(...)`, `bread.exec(...)`, etc).
//!
//! This module owns TOML parsing and validation only; it has no `mlua`
//! dependency so it can be unit-tested in isolation. The `bread.rules`
//! built-in Lua module (`breadd/src/lua/mod.rs`, `BUILTIN_RULES`) is the
//! other half — it takes the [`ParsedRule`]s this module produces and turns
//! each one into a real `bread.on()` subscription.
//!
//! Schema:
//!
//! ```toml
//! [[rule]]
//! on = "device.dock.connected" # matched against "bread." .. on, wildcards allowed
//! run = "~/.config/bread/scripts/dock-connected.sh"
//!
//! [[rule]]
//! on = "power.ac.disconnected"
//! notify = "Unplugged"
//!
//! [[rule]]
//! on = "device.keyboard.connected"
//! exec = "xset r rate 200 40"
//! ```
//!
//! Exactly one of `run` / `notify` / `exec` must be set per rule. `run` and
//! `exec` both ultimately shell out via `bread.exec()`, but with distinct
//! semantics documented on [`RuleAction`].
use std::path::Path;
use serde::Deserialize;
#[derive(Debug, Default, Deserialize)]
struct RulesFile {
#[serde(default, rename = "rule")]
rule: Vec<RawRule>,
}
#[derive(Debug, Default, Deserialize)]
struct RawRule {
on: Option<String>,
run: Option<String>,
notify: Option<String>,
exec: Option<String>,
}
/// The action a validated rule fires when its event matches.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RuleAction {
/// Path to a single script/executable. Treated as exactly one program —
/// tilde-expanded and shell-quoted as a whole before being handed to
/// `bread.exec()`, so a path containing spaces still runs as one file
/// rather than being word-split into a command plus arguments.
Run(String),
/// A raw shell command line, passed to `bread.exec()` verbatim (same as
/// calling `bread.exec()` from hand-written Lua) — you're responsible
/// for quoting/escaping exactly as if you'd typed it in a shell.
Exec(String),
/// A desktop notification message, passed to `bread.notify()`.
Notify(String),
}
/// A `[[rule]]` entry that passed validation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParsedRule {
/// Event-name suffix, e.g. `"device.dock.connected"`. The real
/// subscription is `"bread." .. on` — wildcards (`*`, `**`, `?`) are
/// whatever `bread.on()` itself supports, since this is handed straight
/// through.
pub on: String,
pub action: RuleAction,
}
/// A `[[rule]]` entry that failed validation — reported, not silently
/// dropped, so it shows up via `bread doctor` the same way a broken Lua
/// module would.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RuleIssue {
/// Zero-based position of the `[[rule]]` table in the file.
pub index: usize,
/// The rule's `on` value, if it had one (helps identify *which* rule in
/// a large file when `on` itself isn't the problem).
pub on: Option<String>,
pub message: String,
}
impl std::fmt::Display for RuleIssue {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match &self.on {
Some(on) => write!(f, "rule #{} (on = \"{}\"): {}", self.index, on, self.message),
None => write!(f, "rule #{}: {}", self.index, self.message),
}
}
}
/// Result of attempting to load `rules.toml`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RulesLoadOutcome {
/// The file doesn't exist. Not an error — `rules.toml` is entirely
/// optional and purely additive alongside `init.lua`.
Absent,
/// The file exists but couldn't be read, or doesn't parse as TOML at
/// all — no rules could be recovered from it.
Fatal(String),
/// The file parsed as TOML. `rules` are the entries that passed
/// validation (register these); `issues` describes any `[[rule]]`
/// entries that didn't (report these, but they don't block the rest of
/// the file from working).
Loaded {
rules: Vec<ParsedRule>,
issues: Vec<RuleIssue>,
},
}
/// Location of `rules.toml` — re-exported from `core::config` (single
/// source of truth, colocated with `config_path()`'s identical
/// `XDG_CONFIG_HOME`-vs-`HOME` resolution for `breadd.toml`) so callers that
/// only care about rules loading can reach it as `rules::rules_path()`.
pub use crate::core::config::rules_path;
/// Reads and validates `rules.toml` at `path`. Never panics — every failure
/// mode (missing file, unreadable file, invalid TOML, invalid individual
/// rules) is represented in the returned [`RulesLoadOutcome`].
pub fn load_rules(path: &Path) -> RulesLoadOutcome {
if !path.exists() {
return RulesLoadOutcome::Absent;
}
let raw = match std::fs::read_to_string(path) {
Ok(s) => s,
Err(e) => return RulesLoadOutcome::Fatal(format!("failed to read rules.toml: {e}")),
};
let parsed: RulesFile = match toml::from_str(&raw) {
Ok(v) => v,
Err(e) => return RulesLoadOutcome::Fatal(format!("failed to parse rules.toml: {e}")),
};
let mut rules = Vec::new();
let mut issues = Vec::new();
for (index, raw_rule) in parsed.rule.into_iter().enumerate() {
match validate_rule(index, raw_rule) {
Ok(rule) => rules.push(rule),
Err(issue) => issues.push(issue),
}
}
RulesLoadOutcome::Loaded { rules, issues }
}
fn validate_rule(index: usize, raw: RawRule) -> Result<ParsedRule, RuleIssue> {
let on = raw.on.filter(|s| !s.trim().is_empty());
let mut present = Vec::new();
if raw.run.is_some() {
present.push("run");
}
if raw.notify.is_some() {
present.push("notify");
}
if raw.exec.is_some() {
present.push("exec");
}
let Some(on) = on else {
return Err(RuleIssue {
index,
on: None,
message: "missing or empty `on`".to_string(),
});
};
if present.is_empty() {
return Err(RuleIssue {
index,
on: Some(on),
message: "must set exactly one of `run`, `notify`, `exec` (none set)".to_string(),
});
}
if present.len() > 1 {
return Err(RuleIssue {
index,
on: Some(on),
message: format!(
"must set exactly one of `run`, `notify`, `exec` (found: {})",
present.join(", ")
),
});
}
let action = if let Some(v) = raw.run {
RuleAction::Run(v)
} else if let Some(v) = raw.notify {
RuleAction::Notify(v)
} else {
RuleAction::Exec(raw.exec.expect("exactly one action present"))
};
Ok(ParsedRule { on, action })
}
#[cfg(test)]
mod tests {
use super::*;
use std::io::Write;
use std::path::PathBuf;
fn write_temp(contents: &str) -> (tempfile::TempDir, PathBuf) {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("rules.toml");
let mut f = std::fs::File::create(&path).expect("create rules.toml");
f.write_all(contents.as_bytes()).expect("write rules.toml");
(dir, path)
}
#[test]
fn absent_file_is_not_an_error() {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("does-not-exist.toml");
assert_eq!(load_rules(&path), RulesLoadOutcome::Absent);
}
#[test]
fn invalid_toml_is_fatal() {
let (_dir, path) = write_temp("[[rule\nbroken");
match load_rules(&path) {
RulesLoadOutcome::Fatal(msg) => assert!(msg.contains("failed to parse")),
other => panic!("expected Fatal, got {other:?}"),
}
}
#[test]
fn empty_file_loads_with_no_rules() {
let (_dir, path) = write_temp("");
assert_eq!(
load_rules(&path),
RulesLoadOutcome::Loaded {
rules: vec![],
issues: vec![],
}
);
}
#[test]
fn well_formed_rules_all_three_action_kinds_parse() {
let (_dir, path) = write_temp(
r#"
[[rule]]
on = "device.dock.connected"
run = "~/.config/bread/scripts/dock-connected.sh"
[[rule]]
on = "power.ac.disconnected"
notify = "Unplugged"
[[rule]]
on = "device.keyboard.connected"
exec = "xset r rate 200 40"
"#,
);
let RulesLoadOutcome::Loaded { rules, issues } = load_rules(&path) else {
panic!("expected Loaded");
};
assert!(issues.is_empty());
assert_eq!(
rules,
vec![
ParsedRule {
on: "device.dock.connected".to_string(),
action: RuleAction::Run(
"~/.config/bread/scripts/dock-connected.sh".to_string()
),
},
ParsedRule {
on: "power.ac.disconnected".to_string(),
action: RuleAction::Notify("Unplugged".to_string()),
},
ParsedRule {
on: "device.keyboard.connected".to_string(),
action: RuleAction::Exec("xset r rate 200 40".to_string()),
},
]
);
}
#[test]
fn wildcard_on_is_passed_through_unvalidated() {
let (_dir, path) = write_temp(
r#"
[[rule]]
on = "device.*.connected"
exec = "true"
"#,
);
let RulesLoadOutcome::Loaded { rules, issues } = load_rules(&path) else {
panic!("expected Loaded");
};
assert!(issues.is_empty());
assert_eq!(rules[0].on, "device.*.connected");
}
#[test]
fn missing_on_is_reported_with_index_and_no_on() {
let (_dir, path) = write_temp(
r#"
[[rule]]
exec = "true"
"#,
);
let RulesLoadOutcome::Loaded { rules, issues } = load_rules(&path) else {
panic!("expected Loaded");
};
assert!(rules.is_empty());
assert_eq!(issues.len(), 1);
assert_eq!(issues[0].index, 0);
assert_eq!(issues[0].on, None);
assert!(issues[0].message.contains("missing or empty"));
}
#[test]
fn empty_on_is_treated_as_missing() {
let (_dir, path) = write_temp(
r#"
[[rule]]
on = " "
exec = "true"
"#,
);
let RulesLoadOutcome::Loaded { issues, .. } = load_rules(&path) else {
panic!("expected Loaded");
};
assert_eq!(issues.len(), 1);
assert!(issues[0].message.contains("missing or empty"));
}
#[test]
fn zero_action_keys_is_reported() {
let (_dir, path) = write_temp(
r#"
[[rule]]
on = "power.ac.disconnected"
"#,
);
let RulesLoadOutcome::Loaded { rules, issues } = load_rules(&path) else {
panic!("expected Loaded");
};
assert!(rules.is_empty());
assert_eq!(issues.len(), 1);
assert_eq!(issues[0].on.as_deref(), Some("power.ac.disconnected"));
assert!(issues[0].message.contains("none set"));
}
#[test]
fn multiple_action_keys_is_reported() {
let (_dir, path) = write_temp(
r#"
[[rule]]
on = "power.ac.disconnected"
notify = "Unplugged"
exec = "true"
"#,
);
let RulesLoadOutcome::Loaded { rules, issues } = load_rules(&path) else {
panic!("expected Loaded");
};
assert!(rules.is_empty());
assert_eq!(issues.len(), 1);
assert!(issues[0].message.contains("notify"));
assert!(issues[0].message.contains("exec"));
}
#[test]
fn one_bad_rule_does_not_block_other_valid_rules() {
let (_dir, path) = write_temp(
r#"
[[rule]]
on = "device.dock.connected"
exec = "true"
[[rule]]
notify = "no on here"
[[rule]]
on = "power.ac.disconnected"
notify = "Unplugged"
"#,
);
let RulesLoadOutcome::Loaded { rules, issues } = load_rules(&path) else {
panic!("expected Loaded");
};
assert_eq!(rules.len(), 2);
assert_eq!(issues.len(), 1);
assert_eq!(issues[0].index, 1);
}
#[test]
fn rule_issue_display_includes_index_and_on() {
let issue = RuleIssue {
index: 2,
on: Some("power.ac.disconnected".to_string()),
message: "must set exactly one of `run`, `notify`, `exec` (none set)".to_string(),
};
assert_eq!(
issue.to_string(),
"rule #2 (on = \"power.ac.disconnected\"): must set exactly one of `run`, `notify`, `exec` (none set)"
);
}
}

138
breadd/src/lua/mod.rs
View file

@ -19,6 +19,7 @@ use tokio::time::{interval_at, sleep, Instant};
use tracing::{error, info, warn};
use crate::core::config::{Config, ModulesConfig, NotificationsConfig};
use crate::core::rules::{self, RuleAction, RulesLoadOutcome};
use crate::core::state_engine::StateHandle;
use crate::core::subscriptions::SubscriptionId;
use crate::core::types::{
@ -285,6 +286,7 @@ impl LuaEngine {
self.install_api()?;
self.load_device_rules()?;
self.load_profiles()?;
self.load_rules_toml()?;
self.load_init_and_modules()?;
self.run_on_reload();
@ -1319,6 +1321,70 @@ impl LuaEngine {
.map_err(|e| anyhow!("profiles.lua error: {e}"))
}
/// Reads and validates `rules.toml` (if present) and stashes the result
/// in Lua globals for `bread.rules`'s `on_load()` to pick up once
/// `load_init_and_modules()` loads that built-in module. See the
/// `BUILTIN_RULES` doc comment for why globals rather than generating
/// Lua source text: the rule data is dynamic (comes from a config file
/// parsed fresh each reload) while `ModuleDecl::source` is a
/// `&'static str`, so passing it as real Lua values via `mlua`'s Table
/// API sidesteps ever having to hand-escape a path or shell command
/// into a Lua string literal.
fn load_rules_toml(&self) -> Result<()> {
let path = rules::rules_path();
match rules::load_rules(&path) {
RulesLoadOutcome::Absent => Ok(()),
RulesLoadOutcome::Fatal(msg) => {
self.lua.globals().set("__rules_fatal", msg)?;
Ok(())
}
RulesLoadOutcome::Loaded { rules, issues } => {
let data = self.lua.create_table()?;
for (i, rule) in rules.iter().enumerate() {
let tbl = self.lua.create_table()?;
tbl.set("on", rule.on.clone())?;
match &rule.action {
// `run` names exactly one program: tilde-expand it
// the same way `bread.fs.*`/`bread.exec` callers
// would, then shell-quote the whole thing so a path
// containing spaces still runs as one file rather
// than being word-split by the `sh -c` that
// `bread.exec()` runs it through.
RuleAction::Run(path) => {
let expanded = lua_expand_path(path);
let quoted = shell_quote(&expanded.to_string_lossy());
tbl.set("run", quoted)?;
}
// `exec` is a full shell command line — pass it
// through to `bread.exec()` verbatim, exactly like
// hand-written Lua calling `bread.exec()` directly.
RuleAction::Exec(cmd) => {
tbl.set("exec", cmd.clone())?;
}
RuleAction::Notify(message) => {
tbl.set("notify", message.clone())?;
}
}
data.set(i + 1, tbl)?;
}
self.lua.globals().set("__rules_data", data)?;
if !issues.is_empty() {
let combined = issues
.iter()
.map(|issue| issue.to_string())
.collect::<Vec<_>>()
.join("; ");
self.lua
.globals()
.set("__rules_warning", format!("rules.toml: {combined}"))?;
}
Ok(())
}
}
}
fn load_init_and_modules(&self) -> Result<()> {
self.load_lua_file(&self.entry_point, "init", false)?;
@ -2602,6 +2668,15 @@ fn lua_expand_path(path: &str) -> std::path::PathBuf {
std::path::PathBuf::from(path)
}
/// POSIX single-quotes `s` for safe embedding as one token in a `sh -c`
/// command line — used for `rules.toml`'s `run = "<script path>"` action
/// (see `LuaEngine::load_rules_toml`), which is meant to name exactly one
/// program regardless of spaces in its path, unlike `exec = "..."` which is
/// a full command line handed to the shell as-is.
fn shell_quote(s: &str) -> String {
format!("'{}'", s.replace('\'', r"'\''"))
}
fn dirs_home() -> Option<std::path::PathBuf> {
if let Ok(home) = std::env::var("HOME") {
return Some(std::path::PathBuf::from(home));
@ -2890,6 +2965,68 @@ end
return M
"#;
// `bread.rules` — the Lua half of the `rules.toml` declarative automation
// layer (see `crate::core::rules` for TOML parsing/validation). This module
// itself is static like the other built-ins; the *data* it acts on is
// dynamic (parsed from the user's rules.toml each reload), so it's threaded
// through via `__rules_data` / `__rules_fatal` / `__rules_warning` globals
// that `load_rules_toml()` sets just before `load_init_and_modules()` runs
// this module's `on_load()` — the same "stash data in a global, consume it
// from a lifecycle hook, then clear it" technique `load_profiles()` already
// uses for `__profiles_path`.
//
// A fatal problem (rules.toml unreadable or not valid TOML) is surfaced by
// calling Lua's `error()`, which `run_on_load()` propagates back to
// `load_module()` exactly like any other module's `on_load` failure — so it
// shows up in `bread doctor` / `modules.list` as `bread.rules` in
// `load_error` state with a `last_error`, the same path a broken
// hand-written Lua module's error already takes. A handful of individually
// malformed `[[rule]]` entries (bad `on`, wrong number of action keys)
// aren't fatal to the rest of the file: the valid rules register first (so
// they keep working), then the collected issue list is raised the same way
// so it's still doctor-visible rather than a silent no-op.
const BUILTIN_RULES: &str = r#"
local M = bread.module({ name = "bread.rules", version = "1.0.0" })
local function run_action(rule)
if rule.run then
bread.exec(rule.run)
elseif rule.exec then
bread.exec(rule.exec)
elseif rule.notify then
bread.notify(rule.notify)
end
end
function M.on_load()
if __rules_fatal then
local msg = __rules_fatal
__rules_fatal = nil
__rules_data = nil
__rules_warning = nil
error(msg)
end
local data = __rules_data
__rules_data = nil
if data then
for _, rule in ipairs(data) do
bread.on("bread." .. rule.on, function(event)
run_action(rule)
end)
end
end
if __rules_warning then
local msg = __rules_warning
__rules_warning = nil
error(msg)
end
end
return M
"#;
fn builtin_module_decls(disabled: &HashSet<String>) -> Vec<ModuleDecl> {
let mut out = Vec::new();
@ -2903,6 +3040,7 @@ fn builtin_module_decls(disabled: &HashSet<String>) -> Vec<ModuleDecl> {
BUILTIN_WORKSPACES,
),
("bread.binds", "1.0.0", Vec::new(), BUILTIN_BINDS),
("bread.rules", "1.0.0", Vec::new(), BUILTIN_RULES),
];
for (name, version, after, source) in entries {

216
breadd/tests/ipc_integration.rs
View file

@ -617,6 +617,210 @@ async fn workflow_captures_error_on_failure() -> Result<()> {
Ok(())
}
#[tokio::test]
async fn rules_toml_absent_is_a_no_op() -> Result<()> {
// No rules.toml written at all — the daemon must still start cleanly
// and `bread.rules` (always present as a built-in) must come up
// `loaded` with nothing registered, not `load_error` or `not_found`.
let harness = TestHarness::spawn()?;
harness.wait_until_ready().await?;
let health = harness.send_request("health", json!({})).await?;
let modules = health
.get("modules")
.and_then(Value::as_array)
.expect("modules array");
let rules_mod = modules
.iter()
.find(|m| m.get("name").and_then(Value::as_str) == Some("bread.rules"))
.expect("bread.rules should always be registered as a built-in");
assert_eq!(
rules_mod.get("status").and_then(Value::as_str),
Some("loaded")
);
assert!(rules_mod.get("last_error").and_then(Value::as_str).is_none());
harness.shutdown();
Ok(())
}
#[tokio::test]
async fn rules_toml_well_formed_all_action_kinds_work_end_to_end() -> Result<()> {
use std::os::unix::fs::PermissionsExt;
let assets = tempfile::tempdir()?;
// Deliberately includes a space to prove `run` shell-quotes the whole
// path rather than letting `sh -c` word-split it into "dock" + "sh".
let script_path = assets.path().join("dock connected.sh");
let run_marker = assets.path().join("run-marker");
let exec_marker = assets.path().join("exec-marker");
fs::write(
&script_path,
format!("#!/bin/sh\ntouch '{}'\n", run_marker.display()),
)?;
let mut perms = fs::metadata(&script_path)?.permissions();
perms.set_mode(0o755);
fs::set_permissions(&script_path, perms)?;
let rules_toml = format!(
r#"
[[rule]]
on = "device.dock.connected"
run = "{run_path}"
[[rule]]
on = "power.ac.disconnected"
notify = "Unplugged"
[[rule]]
on = "device.keyboard.connected"
exec = "touch '{exec_path}'"
"#,
run_path = script_path.display(),
exec_path = exec_marker.display(),
);
let harness = TestHarness::spawn_with_init_and_rules(
"bread.on('bread.system.startup', function() end)\n",
Some(&rules_toml),
)?;
harness.wait_until_ready().await?;
// rules.toml parsed and registered cleanly — no load_error.
let health = harness.send_request("health", json!({})).await?;
let modules = health
.get("modules")
.and_then(Value::as_array)
.expect("modules array");
let rules_mod = modules
.iter()
.find(|m| m.get("name").and_then(Value::as_str) == Some("bread.rules"))
.expect("bread.rules present");
assert_eq!(
rules_mod.get("status").and_then(Value::as_str),
Some("loaded"),
"unexpected bread.rules status: {rules_mod:?}"
);
// `run`: fire the matching event and expect the script to have run.
harness
.send_request(
"emit",
json!({"event": "bread.device.dock.connected", "data": {}}),
)
.await?;
wait_for_file(&run_marker).await?;
// `exec`: same, via a raw shell command instead of a script file.
harness
.send_request(
"emit",
json!({"event": "bread.device.keyboard.connected", "data": {}}),
)
.await?;
wait_for_file(&exec_marker).await?;
// `notify`: bread.notify() always emits bread.notify.sent regardless of
// whether a real notify-send binary is available, so that's the
// deterministic way to observe it fired with the right message.
harness
.send_request(
"emit",
json!({"event": "bread.power.ac.disconnected", "data": {}}),
)
.await?;
sleep(Duration::from_millis(150)).await;
let replay = harness
.send_request("events.replay", json!({"since_ms": 10_000}))
.await?;
let sent = replay
.as_array()
.expect("replay array")
.iter()
.find(|e| e.get("event").and_then(Value::as_str) == Some("bread.notify.sent"))
.expect("bread.notify.sent should have been emitted");
assert_eq!(
sent.get("data")
.and_then(|d| d.get("message"))
.and_then(Value::as_str),
Some("Unplugged")
);
harness.shutdown();
Ok(())
}
#[tokio::test]
async fn rules_toml_malformed_rule_surfaces_doctor_visible_error() -> Result<()> {
// Rule #0 is fine; rule #1 has no action key at all.
let rules_toml = r#"
[[rule]]
on = "device.dock.connected"
exec = "true"
[[rule]]
on = "power.ac.disconnected"
"#;
let harness = TestHarness::spawn_with_init_and_rules(
"bread.on('bread.system.startup', function() end)\n",
Some(rules_toml),
)?;
harness.wait_until_ready().await?;
let health = harness.send_request("health", json!({})).await?;
let modules = health
.get("modules")
.and_then(Value::as_array)
.expect("modules array");
let rules_mod = modules
.iter()
.find(|m| m.get("name").and_then(Value::as_str) == Some("bread.rules"))
.expect("bread.rules present");
assert_eq!(
rules_mod.get("status").and_then(Value::as_str),
Some("load_error"),
"malformed rule should surface as load_error: {rules_mod:?}"
);
let last_error = rules_mod
.get("last_error")
.and_then(Value::as_str)
.expect("last_error should be set");
assert!(
last_error.contains("rule #1"),
"expected the bad rule's index in the error, got: {last_error}"
);
assert!(
last_error.contains("must set exactly one"),
"expected the validation message, got: {last_error}"
);
// The daemon itself must not have crashed — still reachable.
let ping = harness.send_request("ping", json!({})).await?;
assert_eq!(ping.get("ok").and_then(Value::as_bool), Some(true));
harness.shutdown();
Ok(())
}
/// Polls for `path` to exist, or times out after 5 seconds — `bread.exec`
/// is fire-and-forget (spawn_blocking + `sh -c`), so its side effects land
/// asynchronously relative to the IPC call that triggered them.
async fn wait_for_file(path: &Path) -> Result<()> {
let deadline = Instant::now() + Duration::from_secs(5);
while Instant::now() < deadline {
if path.exists() {
return Ok(());
}
sleep(Duration::from_millis(50)).await;
}
Err(anyhow!(
"expected file was not created in time: {}",
path.display()
))
}
/// Polls `workflows.list` until `name` is present with `expected_state`, or
/// times out after 5 seconds. Returns the matching entry.
async fn poll_workflow_status(
@ -656,6 +860,14 @@ impl TestHarness {
}
fn spawn_with_init(init_lua: &str) -> Result<Self> {
Self::spawn_with_init_and_rules(init_lua, None)
}
/// Like `spawn_with_init`, but also writes `rules.toml` (when `Some`)
/// into the same synthetic `~/.config/bread` before starting the
/// daemon, and exposes the synthetic `$HOME` so tests can point a
/// `run = "..."` rule at a script file they've written under it.
fn spawn_with_init_and_rules(init_lua: &str, rules_toml: Option<&str>) -> Result<Self> {
let temp = tempfile::tempdir()?;
let runtime_dir = temp.path().join("runtime");
let config_home = temp.path().join("config");
@ -669,6 +881,10 @@ impl TestHarness {
fs::write(bread_cfg.join("init.lua"), init_lua)?;
if let Some(rules_toml) = rules_toml {
fs::write(bread_cfg.join("rules.toml"), rules_toml)?;
}
fs::write(
bread_cfg.join("breadd.toml"),
r#"