Hooks: pre-commit, post-commit, pre-push, post-fetch, post-checkout with JSON payloads; semantic-deps hook behind hooks.semantic-deps (spec 0.6k) 6d3eefbce2f0

//! Client hooks (spec §20): executables in `.oxy/hooks/<event>`, never

//! cloned. Each receives one JSON object on stdin; `pre-*` hooks block the

//! operation by exiting non-zero, and their stderr becomes the error. The

//! `semantic-deps` hook runs only when `hooks.semantic-deps = true` and

//! answers `{"deps": ["<hash hex>", ...]}`.

use super::*;

use std::process::{Command, Stdio};

/// Minimal JSON string escaping.

pub fn json_str(s: &str) -> String {

    let mut out = String::with_capacity(s.len() + 2);

    out.push('"');

    for c in s.chars() {

        match c {

            '"' => out.push_str("\\\""),

            '\\' => out.push_str("\\\\"),

            '\n' => out.push_str("\\n"),

            '\r' => out.push_str("\\r"),

            '\t' => out.push_str("\\t"),

            c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)),

            c => out.push(c),

        }

    }

    out.push('"');

    out

}

pub fn json_array<I: IntoIterator<Item = String>>(items: I) -> String {

    format!("[{}]", items.into_iter().collect::<Vec<_>>().join(","))

}

/// What running a hook produced.

#[derive(Debug, Clone, PartialEq, Eq)]

pub struct HookOutcome {

    pub ran: bool,

    pub stdout: String,

}

impl Repo {

    fn hook_path(&self, event: &str) -> PathBuf {

        self.oxy.join("hooks").join(event)

    }

    /// Run the hook for `event` with `input` on stdin, if one exists and is

    /// executable. A non-zero exit is an error carrying the hook's stderr.

    pub fn run_hook(&self, event: &str, input: &str) -> Result<HookOutcome> {

        let path = self.hook_path(event);

        if !path.is_file() {

            return Ok(HookOutcome { ran: false, stdout: String::new() });

        }

        let mut child = Command::new(&path)

            .current_dir(&self.root)

            .env("OXY_EVENT", event)

            .env("OXY_ROOT", &self.root)

            .stdin(Stdio::piped())

            .stdout(Stdio::piped())

            .stderr(Stdio::piped())

            .spawn()

            .map_err(|e| RepoError::Msg(format!("running hook {event}: {e}")))?;

        if let Some(mut stdin) = child.stdin.take() {

            let _ = stdin.write_all(input.as_bytes());

        }

        let out = child.wait_with_output()?;

        let stdout = String::from_utf8_lossy(&out.stdout).to_string();

        if !out.status.success() {

            let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();

            return fail(format!("hook {event} refused: {}", if stderr.is_empty() { "(no message)".to_string() } else { stderr }));

        }

        Ok(HookOutcome { ran: true, stdout })

    }

    /// Extra dependencies from the `semantic-deps` hook (spec §8.1, §20).

    pub(crate) fn semantic_deps(&self, change_id: &ChangeId, touched: &[String], candidates: &[(ChangeId, ChangeHash, Vec<String>)]) -> Result<Vec<ChangeHash>> {

        if !self.config.semantic_deps {

            return Ok(vec![]);

        }

        let input = format!(

            "{{\"change_id\":{},\"touched_paths\":{},\"candidate_deps\":{}}}",

            json_str(&change_id.to_hex()),

            json_array(touched.iter().map(|p| json_str(p))),

            json_array(candidates.iter().map(|(id, h, paths)| format!("{{\"change_id\":{},\"hash\":{},\"paths\":{}}}", json_str(&id.to_hex()), json_str(&h.to_hex()), json_array(paths.iter().map(|p| json_str(p))))))

        );

        let out = self.run_hook("semantic-deps", &input)?;

        if !out.ran {

            return Ok(vec![]);

        }

        // Accept every 64-hex token after "deps"; any other shape is ignored.

        let body = out.stdout.split_once("\"deps\"").map(|(_, rest)| rest.to_string()).unwrap_or_default();

        let mut deps = Vec::new();

        let bytes = body.as_bytes();

        let mut i = 0;

        while i + 64 <= bytes.len() {

            if bytes[i..i + 64].iter().all(|b| b.is_ascii_hexdigit()) && (i == 0 || !bytes[i - 1].is_ascii_hexdigit()) && (i + 64 == bytes.len() || !bytes[i + 64].is_ascii_hexdigit()) {

                if let Some(h) = ObjectRef::from_hex(&body[i..i + 64]) {

                    deps.push(h);

                }

                i += 64;

            } else {

                i += 1;

            }

        }

        Ok(deps)

    }

}

        let wc = self.new_working_copy(heads.clone(), "");

        let _ = self.run_hook(

            "post-checkout",

            &format!("{{\"event\":\"post-checkout\",\"heads\":{},\"written\":{},\"removed\":{}}}", json_array(heads.iter().map(|h| json_str(&h.to_hex()))), report.written, report.removed),

        );

    /// `hooks.semantic-deps`: run the semantic-deps hook at commit (spec §20).

    pub semantic_deps: bool,

            semantic_deps: false,

            "hooks.semantic-deps" => self.semantic_deps = matches!(value, "true" | "1" | "yes"),

mod hooks;

pub use hooks::{json_array, json_str, HookOutcome};

        // pre-commit hook: may veto.

        self.run_hook(

            "pre-commit",

            &format!(

                "{{\"event\":\"pre-commit\",\"message\":{},\"paths\":{}}}",

                json_str(message),

                json_array(snap.statuses.iter().map(|s| format!("{{\"path\":{},\"status\":{}}}", json_str(&s.path), json_str(&format!("{:?}", s.status)))))

            ),

        )?;

        // semantic-deps hook: may add explicit dependencies (spec §8.1).

        if self.config.semantic_deps {

            let touched: Vec<String> = snap.statuses.iter().map(|s| s.path.clone()).collect();

            let by_node = snap.base_snapshot.tree.by_node();

            let mut candidates: Vec<(ChangeId, ChangeHash, Vec<String>)> = Vec::new();

            let mut seen: BTreeSet<ChangeHash> = BTreeSet::new();

            for h in deps.iter().chain(snap.base.maximal(&snap.wc.deps).iter()) {

                if !seen.insert(*h) {

                    continue;

                }

                let c = self.store.get_change(h)?;

                let mut paths: BTreeSet<String> = BTreeSet::new();

                for n in c.tree_ops.iter().map(|o| o.node()).chain(c.edits.iter().map(|e| e.node())) {

                    if let Some(e) = by_node.get(&n) {

                        paths.insert(e.path.clone());

                    }

                }

                candidates.push((c.change_id, *h, paths.into_iter().collect()));

            }

            for d in self.semantic_deps(&snap.wc.change_id, &touched, &candidates)? {

                if snap.base.contains(&d) {

                    deps.insert(d);

                }

            }

        }

        let _ = self.run_hook("post-commit", &format!("{{\"event\":\"post-commit\",\"change_id\":{},\"hash\":{},\"message\":{}}}", json_str(&snap.wc.change_id.to_hex()), json_str(&hash.to_hex()), json_str(message)));

        let _ = self.run_hook(

            "post-fetch",

            &format!(

                "{{\"event\":\"post-fetch\",\"remote\":{},\"bookmarks\":{}}}",

                json_str(remote_name),

                json_array(report.iter().map(|(n, heads, _)| format!("{{\"name\":{},\"heads\":{}}}", json_str(n), json_array(heads.iter().map(|h| json_str(&h.to_hex()))))))

            ),

        );

        let (op_ref, op) = self.head_op()?;

        let bookmark = self.config.bookmark.clone();

        let local_heads = self.heads_of(&op.view, &bookmark)?;

        // pre-push hook: may veto before the remote is contacted.

        self.run_hook(

            "pre-push",

            &format!("{{\"event\":\"pre-push\",\"remote\":{},\"bookmark\":{},\"heads\":{}}}", json_str(remote_name), json_str(&bookmark), json_array(local_heads.iter().map(|h| json_str(&h.to_hex())))),

        )?;

#[cfg(unix)]

#[test]

fn hooks_can_veto_observe_and_add_dependencies() {

    use std::os::unix::fs::PermissionsExt;

    hermetic();

    let dir = tempfile::tempdir().unwrap();

    let root = dir.path();

    let mut repo = Repo::init(root).unwrap().with_home(root.join("home"));

    let hooks = root.join(".oxy/hooks");

    fs::create_dir_all(&hooks).unwrap();

    let hook = |name: &str, body: &str| {

        let p = hooks.join(name);

        fs::write(&p, format!("#!/bin/sh\n{body}\n")).unwrap();

        fs::set_permissions(&p, fs::Permissions::from_mode(0o755)).unwrap();

    };

    hook("pre-commit", "cat > \"$OXY_ROOT/.last-pre-commit\"; grep -q WIP \"$OXY_ROOT/.last-pre-commit\" && { echo 'no WIP commits' >&2; exit 1; }; exit 0");

    hook("post-commit", "cat > \"$OXY_ROOT/.last-post-commit\"");

    hook("post-checkout", "cat > \"$OXY_ROOT/.last-post-checkout\"");

    hook("pre-push", "echo pushing blocked >&2; exit 3");

    write(root, ".oxyignore", b".last-*\n");

    write(root, "a.txt", b"a\n");

    let err = repo.commit("WIP: nope", &[]).unwrap_err().to_string();

    assert!(err.contains("pre-commit refused: no WIP commits"), "{err}");

    let h1 = repo.commit("first", &[]).unwrap();

    let pre = fs::read_to_string(root.join(".last-pre-commit")).unwrap();

    assert!(pre.contains("\"event\":\"pre-commit\"") && pre.contains("\"path\":\"a.txt\"") && pre.contains("\"message\":\"first\""), "{pre}");

    let post = fs::read_to_string(root.join(".last-post-commit")).unwrap();

    assert!(post.contains(&h1.to_hex()), "{post}");

    repo.checkout(&[h1], false, "co").unwrap();

    assert!(fs::read_to_string(root.join(".last-post-checkout")).unwrap().contains("post-checkout"));

    repo.config.set("remote.origin.url", "/nowhere").unwrap();

    repo.save_config().unwrap();

    let err = repo.push("origin", false).unwrap_err().to_string();

    assert!(err.contains("pre-push refused: pushing blocked"), "{err}");

    // semantic-deps: only when enabled; adds an explicit dependency.

    write(root, "b.txt", b"b\n");

    hook("semantic-deps", &format!("cat > \"$OXY_ROOT/.last-semantic\"; echo '{{\"deps\": [\"{}\"]}}'", h1.to_hex()));

    let h2 = repo.commit("b without hook", &[]).unwrap();

    assert!(repo.store().get_change(&h2).unwrap().deps.is_empty(), "hook disabled by default");

    repo.config.set("hooks.semantic-deps", "true").unwrap();

    repo.save_config().unwrap();

    write(root, "c.txt", b"c\n");

    let h3 = repo.commit("c with hook", &[]).unwrap();

    assert_eq!(repo.store().get_change(&h3).unwrap().deps, vec![h1]);

    let sem = fs::read_to_string(root.join(".last-semantic")).unwrap();

    assert!(sem.contains("\"touched_paths\":[\"c.txt\"]") && sem.contains("candidate_deps"), "{sem}");

    assert_eq!(json_str("a\"b\\c\n"), "\"a\\\"b\\\\c\\n\"");

}

| **Status** | Draft 0.6k |

Client hooks live in `.oxy/hooks/` and are never cloned. Events: `pre-commit`, `semantic-deps`, `post-commit`, `pre-push`, `post-fetch`, `post-checkout`. A hook is an executable named after its event, run in the workspace root with `OXY_EVENT` and `OXY_ROOT` set; it receives one JSON object on stdin and blocks the operation by non-zero exit for `pre-*` events, whose stderr becomes the error message. Payloads: `pre-commit` `{event, message, paths: [{path, status}]}`; `post-commit` `{event, change_id, hash, message}`; `pre-push` `{event, remote, bookmark, heads}`; `post-fetch` `{event, remote, bookmarks: [{name, heads}]}`; `post-checkout` `{event, heads, written, removed}`. Hashes and ids are hex strings.

The `semantic-deps` hook runs during `oxy commit` after the working copy is snapshotted and before the change is finalized. It receives `{ change_id, touched_paths, candidate_deps: [ { change_id, hash, paths } ] }`, where `candidate_deps` are the changes the new change already references plus the heads it sits on, each with the paths it touched, and it returns `{ deps: [hash hex] }` to add to `deps(C)`; hashes not in the base state are ignored. It runs only when `hooks.semantic-deps = true` is set in `.oxy/config`, which is never set by clone.

*Changelog.* Draft 0.6k (2026-09-27): hook execution model and JSON payloads (§20).

Draft 0.6j (2026-09-27): `.oxyattributes` semantics (§19).