use std::ffi::OsStr;
use std::io::{ErrorKind, Write};
use std::path::{Path, PathBuf};
use std::process::Command;
use anyhow::{Context, Result};
use crate::commands::hook::HOOK_EVENTS;
use crate::daemon::render;
use crate::ordered_json::Json;
pub(crate) const TIMEOUT_SECS: u64 = 10;
pub(crate) const SETTINGS_FILE: &str = "settings.json";
const PROGRAM: &str = "sb";
#[derive(Debug, PartialEq)]
pub(crate) enum Outcome {
Unchanged {
path: PathBuf,
},
Registered {
path: PathBuf,
},
NoClaude {
dir: PathBuf,
snippet: String,
},
Unreadable {
path: PathBuf,
detail: String,
snippet: String,
},
}
impl Outcome {
pub(crate) fn report(&self) -> String {
let events = HOOK_EVENTS
.iter()
.map(|e| e.event)
.collect::<Vec<_>>()
.join(", ");
match self {
Outcome::Unchanged { path } => {
format!("{events} hooks already registered in {}", path.display())
}
Outcome::Registered { path } => {
format!("registered {events} hooks in {}", path.display())
}
Outcome::NoClaude { dir, snippet } => format!(
"no Claude Code config dir at {}; once Claude Code is installed, add this to its settings.json:\n{}",
dir.display(),
indent(snippet)
),
Outcome::Unreadable {
path,
detail,
snippet,
} => format!(
"left {} unchanged: {detail}; add this to it by hand:\n{}",
path.display(),
indent(snippet)
),
}
}
}
fn indent(text: &str) -> String {
text.lines()
.map(|line| format!(" {line}"))
.collect::<Vec<_>>()
.join("\n")
}
pub(crate) fn settings_path(config_dir: Option<&OsStr>, home: &Path) -> PathBuf {
match config_dir.filter(|dir| !dir.is_empty()) {
Some(dir) => Path::new(dir).join(SETTINGS_FILE),
None => home.join(".claude").join(SETTINGS_FILE),
}
}
struct Wanted {
event: &'static str,
name: &'static str,
command: String,
}
impl Wanted {
fn group(&self) -> Json {
let handler = Json::object([
("type", Json::from("command")),
("command", Json::from(self.command.as_str())),
("timeout", Json::from(TIMEOUT_SECS)),
]);
Json::object([("hooks", Json::Array(vec![handler]))])
}
fn is_ours(&self, handler: &Json) -> bool {
let Some(command) = handler.get("command").and_then(Json::as_str) else {
return false;
};
if command == self.command {
return true;
}
let Some(words) = shell_words(command) else {
return false;
};
matches!(
words.as_slice(),
[program, hook, name]
if Path::new(program).file_name() == Some(OsStr::new(PROGRAM))
&& hook == "hook"
&& name == self.name
)
}
fn place(&self, groups: Vec<Json>) -> Vec<Json> {
let mut placed = false;
let mut kept = Vec::with_capacity(groups.len() + 1);
for mut group in groups {
let Some(Json::Array(handlers)) = group.get_mut("hooks") else {
kept.push(group);
continue;
};
let before = handlers.len();
handlers.retain(|handler| !self.is_ours(handler));
if handlers.len() == before || !handlers.is_empty() {
kept.push(group);
} else if !placed {
kept.push(self.group());
placed = true;
}
}
if !placed {
kept.push(self.group());
}
kept
}
}
fn wanted(sb_bin: &Path) -> Vec<Wanted> {
HOOK_EVENTS
.iter()
.map(|e| {
let mut command = Command::new(sb_bin);
command.args(["hook", e.name]);
Wanted {
event: e.event,
name: e.name,
command: render(&command),
}
})
.collect()
}
fn snippet(wanted: &[Wanted]) -> String {
let events = wanted
.iter()
.map(|w| (w.event, Json::Array(vec![w.group()])));
let doc = Json::object([("hooks", Json::object(events))]);
serde_json::to_string_pretty(&doc).expect("a JSON tree always serializes")
}
const DOC_NOT_OBJECT: &str = "it is not a JSON object";
const HOOKS_NOT_OBJECT: &str = "its \"hooks\" is not an object";
fn event_not_list(event: &str) -> String {
format!("its hooks.{event} is not a list")
}
fn merge(doc: &mut Json, wanted: &[Wanted]) -> Result<(), String> {
let hooks = doc
.entry("hooks", || Json::Object(Vec::new()))
.ok_or(DOC_NOT_OBJECT)?;
for w in wanted {
let groups = hooks
.entry(w.event, || Json::Array(Vec::new()))
.ok_or(HOOKS_NOT_OBJECT)?;
let Json::Array(list) = groups else {
return Err(event_not_list(w.event));
};
*list = w.place(std::mem::take(list));
}
Ok(())
}
#[derive(Debug, Default, PartialEq)]
pub(crate) struct Audit {
pub(crate) missing: Vec<&'static str>,
pub(crate) stale: Vec<String>,
}
pub(crate) fn audit(doc: &Json, sb_bin: &Path) -> Result<Audit, String> {
let wanted = wanted(sb_bin);
merge(&mut doc.clone(), &wanted)?;
let hooks = doc.get("hooks");
let current = sb_bin.to_string_lossy();
let mut audit = Audit::default();
for w in &wanted {
let groups = match hooks.and_then(|h| h.get(w.event)) {
Some(Json::Array(list)) => list.as_slice(),
_ => &[],
};
let programs: Vec<String> = groups
.iter()
.flat_map(handlers)
.filter(|handler| w.is_ours(handler))
.filter_map(program)
.collect();
if programs.is_empty() {
audit.missing.push(w.event);
}
for program in programs {
if program != current && !audit.stale.contains(&program) {
audit.stale.push(program);
}
}
}
Ok(audit)
}
fn handlers(group: &Json) -> &[Json] {
match group.get("hooks") {
Some(Json::Array(handlers)) => handlers,
_ => &[],
}
}
fn program(handler: &Json) -> Option<String> {
let command = handler.get("command").and_then(Json::as_str)?;
shell_words(command)?.into_iter().next()
}
pub(crate) fn register(settings: &Path, sb_bin: &Path) -> Result<Outcome> {
let wanted = wanted(sb_bin);
let dir = settings.parent().unwrap_or(Path::new("."));
if !dir.is_dir() {
return Ok(Outcome::NoClaude {
dir: dir.to_path_buf(),
snippet: snippet(&wanted),
});
}
let unreadable = |detail: String| Outcome::Unreadable {
path: settings.to_path_buf(),
detail,
snippet: snippet(&wanted),
};
let target = match std::fs::canonicalize(settings) {
Ok(target) => target,
Err(e) if e.kind() == ErrorKind::NotFound => settings.to_path_buf(),
Err(e) => return Ok(unreadable(e.to_string())),
};
let existing = match std::fs::read_to_string(&target) {
Ok(text) => Some(text),
Err(e) if e.kind() == ErrorKind::NotFound => None,
Err(e) => return Ok(unreadable(e.to_string())),
};
let mut doc = match existing.as_deref().map(serde_json::from_str::<Json>) {
None => Json::Object(Vec::new()),
Some(Ok(doc)) => doc,
Some(Err(e)) => return Ok(unreadable(format!("it is not valid JSON ({e})"))),
};
let before = doc.clone();
if let Err(detail) = merge(&mut doc, &wanted) {
return Ok(unreadable(detail));
}
if existing.is_some() && doc == before {
return Ok(Outcome::Unchanged {
path: settings.to_path_buf(),
});
}
write_atomically(&target, &doc)?;
Ok(Outcome::Registered {
path: settings.to_path_buf(),
})
}
fn write_atomically(target: &Path, doc: &Json) -> Result<()> {
let dir = target.parent().unwrap_or(Path::new("."));
let mut text = serde_json::to_string_pretty(doc)?;
text.push('\n');
let mut tmp = tempfile::NamedTempFile::new_in(dir)
.with_context(|| format!("creating a temp file in {}", dir.display()))?;
tmp.write_all(text.as_bytes())?;
match std::fs::metadata(target) {
Ok(meta) => tmp.as_file().set_permissions(meta.permissions())?,
Err(e) if e.kind() == ErrorKind::NotFound => {}
Err(e) => return Err(e).with_context(|| format!("reading {}", target.display())),
}
tmp.as_file().sync_all()?;
tmp.persist(target)
.with_context(|| format!("replacing {}", target.display()))?;
Ok(())
}
fn shell_words(line: &str) -> Option<Vec<String>> {
let mut words = Vec::new();
let mut word: Option<String> = None;
let mut chars = line.chars();
while let Some(c) = chars.next() {
if c.is_whitespace() {
words.extend(word.take());
continue;
}
let current = word.get_or_insert_with(String::new);
match c {
'\'' => loop {
match chars.next()? {
'\'' => break,
c => current.push(c),
}
},
'"' => loop {
match chars.next()? {
'"' => break,
'\\' => {
let next = chars.next()?;
if !matches!(next, '"' | '\\' | '$' | '`') {
current.push('\\');
}
current.push(next);
}
c => current.push(c),
}
},
'\\' => current.push(chars.next()?),
c => current.push(c),
}
}
words.extend(word);
Some(words)
}
#[cfg(test)]
mod tests {
use std::fs;
use serde_json::{Value, json};
use super::*;
use crate::commands::hook::HOOK_EVENTS;
const SB: &str = "/opt/sb tools/bin/sb";
struct Claude {
dir: tempfile::TempDir,
}
impl Claude {
fn new() -> Self {
Claude {
dir: tempfile::tempdir().unwrap(),
}
}
fn settings(&self) -> PathBuf {
self.dir.path().join("settings.json")
}
fn write(&self, text: &str) {
fs::write(self.settings(), text).unwrap();
}
fn text(&self) -> String {
fs::read_to_string(self.settings()).unwrap()
}
fn json(&self) -> Value {
serde_json::from_str(&self.text()).unwrap()
}
fn register(&self, sb: &str) -> Outcome {
register(&self.settings(), Path::new(sb)).unwrap()
}
}
fn ours(sb: &str, name: &str) -> Value {
json!({"hooks": [{
"type": "command",
"command": format!("'{sb}' hook {name}"),
"timeout": TIMEOUT_SECS
}]})
}
fn top_keys(text: &str) -> Vec<String> {
let doc: crate::ordered_json::Json = serde_json::from_str(text).unwrap();
let crate::ordered_json::Json::Object(entries) = doc else {
panic!("{text}")
};
entries.into_iter().map(|(k, _)| k).collect()
}
#[test]
fn hook_events_are_registered_under_their_claude_code_names() {
let names: Vec<(&str, &str)> = HOOK_EVENTS.iter().map(|e| (e.event, e.name)).collect();
for wanted in [
("Stop", "stop"),
("UserPromptSubmit", "prompt"),
("SessionStart", "session-start"),
("SubagentStart", "subagent-start"),
("PostToolUse", "post-tool-use"),
] {
assert!(names.contains(&wanted), "{names:?}");
}
}
#[test]
fn a_binary_under_another_name_is_registered_once() {
let claude = Claude::new();
let renamed = "/opt/tools/second-brain-cli";
claude.register(renamed);
let written = claude.text();
assert!(
matches!(claude.register(renamed), Outcome::Unchanged { .. }),
"{written}"
);
assert_eq!(claude.text(), written);
}
#[test]
fn a_first_run_creates_the_settings_and_a_second_changes_nothing() {
let claude = Claude::new();
let first = claude.register(SB);
assert_eq!(
first,
Outcome::Registered {
path: claude.settings()
}
);
for event in HOOK_EVENTS {
assert_eq!(
claude.json()["hooks"][event.event],
json!([ours(SB, event.name)])
);
}
let written = claude.text();
let second = claude.register(SB);
assert_eq!(
second,
Outcome::Unchanged {
path: claude.settings()
}
);
assert_eq!(claude.text(), written);
}
#[test]
fn foreign_hooks_and_settings_keys_survive_in_their_order() {
let claude = Claude::new();
let original = json!({
"model": "opus",
"hooks": {
"Stop": [
{"hooks": [{"type": "command", "command": "/usr/local/bin/notify done"}]},
{"hooks": [{"type": "command", "command": "sb hook other"}]}
],
"PreToolUse": [
{"matcher": "Bash", "hooks": [{"type": "command", "command": "guard"}]}
]
},
"env": {"Z": "1", "A": "2"},
"alwaysThinkingEnabled": true
});
let text = r#"{
"model": "opus",
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "/usr/local/bin/notify done"
}
]
},
{
"hooks": [
{
"type": "command",
"command": "sb hook other"
}
]
}
],
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "guard"
}
]
}
]
},
"env": {
"Z": "1",
"A": "2"
},
"alwaysThinkingEnabled": true
}
"#;
claude.write(text);
claude.register(SB);
let after = claude.json();
let stop = after["hooks"]["Stop"].as_array().unwrap();
assert_eq!(stop.len(), 3, "{after}");
assert_eq!(stop[0], original["hooks"]["Stop"][0]);
assert_eq!(stop[1], original["hooks"]["Stop"][1]);
assert_eq!(stop[2], ours(SB, "stop"));
assert_eq!(
after["hooks"]["PreToolUse"],
original["hooks"]["PreToolUse"]
);
assert_eq!(after["env"], original["env"]);
assert_eq!(after["model"], "opus");
assert_eq!(after["alwaysThinkingEnabled"], true);
let written = claude.text();
assert_eq!(
top_keys(&written),
["model", "hooks", "env", "alwaysThinkingEnabled"]
);
assert!(written.find("\"Z\"") < written.find("\"A\""), "{written}");
assert!(written.find("\"Stop\"") < written.find("\"PreToolUse\""));
assert!(matches!(claude.register(SB), Outcome::Unchanged { .. }));
assert_eq!(claude.text(), written);
}
#[test]
fn a_stale_path_of_ours_is_replaced_in_place_and_copies_are_dropped() {
let claude = Claude::new();
let text = json!({"hooks": {"Stop": [
{"hooks": [{"type": "command", "command": "/old/bin/sb hook stop", "timeout": 5}]},
{"hooks": [{"type": "command", "command": "keep-me"}]},
{"hooks": [
{"type": "command", "command": "'/other place/sb' hook stop"},
{"type": "command", "command": "also-keep"}
]},
{"hooks": [{"type": "command", "command": "\"/old/bin/sb\" hook stop"}]}
]}});
claude.write(&serde_json::to_string_pretty(&text).unwrap());
assert!(matches!(claude.register(SB), Outcome::Registered { .. }));
assert_eq!(
claude.json()["hooks"]["Stop"],
json!([
ours(SB, "stop"),
{"hooks": [{"type": "command", "command": "keep-me"}]},
{"hooks": [{"type": "command", "command": "also-keep"}]}
])
);
}
#[test]
fn commands_that_only_resemble_ours_are_left_alone() {
let claude = Claude::new();
let foreign = json!([
{"hooks": [{"type": "command", "command": "/bin/sbx hook stop"}]},
{"hooks": [{"type": "command", "command": "sb hook stop --verbose"}]},
{"hooks": [{"type": "command", "command": "sb hook"}]},
{"hooks": [{"type": "command", "command": "'unterminated sb hook stop"}]}
]);
claude.write(&json!({"hooks": {"Stop": foreign}}).to_string());
claude.register(SB);
let mut expected = foreign.as_array().unwrap().clone();
expected.push(ours(SB, "stop"));
assert_eq!(claude.json()["hooks"]["Stop"], Value::Array(expected));
}
#[test]
fn the_settings_file_keeps_its_permissions() {
use std::os::unix::fs::PermissionsExt;
let claude = Claude::new();
claude.write("{}");
fs::set_permissions(claude.settings(), fs::Permissions::from_mode(0o640)).unwrap();
claude.register(SB);
let mode = fs::metadata(claude.settings())
.unwrap()
.permissions()
.mode();
assert_eq!(mode & 0o777, 0o640);
}
#[test]
fn a_symlinked_settings_file_is_written_through_the_link() {
let claude = Claude::new();
let real = claude.dir.path().join("dotfiles.json");
fs::write(&real, "{}").unwrap();
std::os::unix::fs::symlink(&real, claude.settings()).unwrap();
claude.register(SB);
assert!(
fs::symlink_metadata(claude.settings())
.unwrap()
.file_type()
.is_symlink()
);
let written: Value = serde_json::from_str(&fs::read_to_string(&real).unwrap()).unwrap();
assert_eq!(written["hooks"]["Stop"], json!([ours(SB, "stop")]));
}
#[test]
fn the_config_dir_comes_from_claude_config_dir_or_home() {
let home = Path::new("/home/someone");
assert_eq!(
settings_path(Some(OsStr::new("/srv/claude")), home),
Path::new("/srv/claude/settings.json")
);
assert_eq!(
settings_path(None, home),
Path::new("/home/someone/.claude/settings.json")
);
assert_eq!(
settings_path(Some(OsStr::new("")), home),
Path::new("/home/someone/.claude/settings.json")
);
}
#[test]
fn without_a_config_dir_nothing_is_written_and_the_snippet_is_returned() {
let root = tempfile::tempdir().unwrap();
let dir = root.path().join(".claude");
let outcome = register(&dir.join("settings.json"), Path::new(SB)).unwrap();
let Outcome::NoClaude {
dir: named,
snippet,
} = &outcome
else {
panic!("{outcome:?}")
};
assert_eq!(named, &dir);
assert!(!dir.exists());
let parsed: Value = serde_json::from_str(snippet).unwrap();
assert_eq!(parsed["hooks"]["Stop"], json!([ours(SB, "stop")]));
assert!(outcome.report().contains(snippet.lines().next().unwrap()));
}
#[test]
fn an_invalid_settings_file_is_left_untouched() {
let claude = Claude::new();
for text in [
"{\"hooks\": ",
"[]",
"{\"hooks\": []}",
"{\"hooks\": {\"Stop\": {}}}",
] {
claude.write(text);
let outcome = claude.register(SB);
let Outcome::Unreadable { path, snippet, .. } = &outcome else {
panic!("{text}: {outcome:?}")
};
assert_eq!(path, &claude.settings());
assert!(snippet.contains("hook stop"), "{snippet}");
assert_eq!(claude.text(), text);
}
}
#[test]
fn audit_refuses_a_settings_doc_exactly_when_merge_does() {
let sb = Path::new(SB);
for text in [
"[]",
"\"text\"",
"null",
"{}",
"{\"hooks\": {}}",
"{\"hooks\": []}",
"{\"hooks\": null}",
"{\"hooks\": 3}",
"{\"hooks\": {\"Stop\": {}}}",
"{\"hooks\": {\"Stop\": null}}",
"{\"hooks\": {\"SessionStart\": 1, \"Stop\": {}}}",
"{\"hooks\": {\"Stop\": {}, \"SessionStart\": 1}}",
"{\"hooks\": {\"Stop\": [1, \"x\", {\"hooks\": 3}]}}",
"{\"hooks\": {\"Stop\": []}, \"hooks\": []}",
"{\"hooks\": [], \"hooks\": {\"Stop\": []}}",
"{\"hooks\": {\"Stop\": {}, \"Stop\": []}}",
] {
let doc: Json = serde_json::from_str(text).unwrap();
let merged = merge(&mut doc.clone(), &wanted(sb));
let audited = audit(&doc, sb).map(|_| ());
assert_eq!(audited, merged, "{text}");
}
}
#[test]
fn audit_refusals_keep_the_texts_setup_reports() {
let sb = Path::new(SB);
let refusal = |text: &str| audit(&serde_json::from_str(text).unwrap(), sb).unwrap_err();
assert_eq!(refusal("[]"), "it is not a JSON object");
assert_eq!(refusal("{\"hooks\": []}"), "its \"hooks\" is not an object");
assert_eq!(
refusal("{\"hooks\": {\"Stop\": {}}}"),
"its hooks.Stop is not a list"
);
}
#[test]
fn shell_words_undo_the_quoting_setup_writes() {
for path in [
"/plain/sb",
"/a b/sb",
"/it's/sb",
"/$HOME/`x`/sb",
"/tab\there/sb",
] {
let mut cmd = Command::new(path);
cmd.args(["hook", "stop"]);
assert_eq!(
shell_words(&render(&cmd)).unwrap(),
[path, "hook", "stop"],
"{path}"
);
}
assert_eq!(
shell_words(r#" "/x \"y\"\n/sb" hook\ s "#).unwrap(),
[r#"/x "y"\n/sb"#, "hook s"]
);
assert_eq!(shell_words("''").unwrap(), [""]);
assert!(shell_words("\"open").is_none());
}
#[test]
fn a_plain_path_is_written_unquoted_and_recognized_on_the_next_run() {
let claude = Claude::new();
claude.register("/usr/local/bin/sb");
assert_eq!(
claude.json()["hooks"]["Stop"][0]["hooks"][0]["command"],
"/usr/local/bin/sb hook stop"
);
assert!(matches!(
claude.register("/usr/local/bin/sb"),
Outcome::Unchanged { .. }
));
}
}