openlatch-client 0.1.14

/// JSONC string surgery for `settings.json`.
///
/// Uses `jsonc_parser`'s CST API to locate insertion points in the raw string,
/// insert or replace entries by their `_openlatch` marker, and produce a
/// modified string that preserves all comments, whitespace, and trailing commas
/// in untouched regions.
///
/// # Design (D-12)
///
/// We operate at the string/CST level, NOT via full deserialisation + re-serialisation.
/// This guarantees that every byte outside our target arrays is preserved verbatim.
use std::path::Path;

use crate::error::OlError;

// Re-export hook error codes used in tests.
pub use crate::error::{ERR_HOOK_AGENT_NOT_FOUND, ERR_HOOK_MALFORMED_JSONC, ERR_HOOK_WRITE_FAILED};

/// Read the JSONC settings file, or create it with `{}` if it does not exist.
///
/// Returns the raw JSONC string ready for surgery.
///
/// # Errors
///
/// - `OL-1401` if the file cannot be read or created.
pub fn read_or_create_settings(path: &Path) -> Result<String, OlError> {
    if path.exists() {
        std::fs::read_to_string(path).map_err(|e| {
            OlError::new(
                ERR_HOOK_WRITE_FAILED,
                format!("Cannot read settings.json: {e}"),
            )
            .with_suggestion("Check file permissions.")
            .with_docs("https://docs.openlatch.ai/errors/OL-1401")
        })
    } else {
        // Create parent directories if needed.
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent).map_err(|e| {
                OlError::new(
                    ERR_HOOK_WRITE_FAILED,
                    format!("Cannot create settings directory: {e}"),
                )
                .with_suggestion("Check file permissions.")
                .with_docs("https://docs.openlatch.ai/errors/OL-1401")
            })?;
        }
        std::fs::write(path, "{}").map_err(|e| {
            OlError::new(
                ERR_HOOK_WRITE_FAILED,
                format!("Cannot create settings.json: {e}"),
            )
            .with_suggestion("Check file permissions.")
            .with_docs("https://docs.openlatch.ai/errors/OL-1401")
        })?;
        Ok("{}".to_string())
    }
}

/// Convert a `serde_json::Value` into the CST's `CstInputValue` type.
///
/// This enables us to insert arbitrary JSON values into the CST while preserving
/// surrounding JSONC structure (comments, trailing commas, whitespace).
fn serde_to_cst_input(v: serde_json::Value) -> jsonc_parser::cst::CstInputValue {
    use jsonc_parser::cst::CstInputValue;
    match v {
        serde_json::Value::Null => CstInputValue::Null,
        serde_json::Value::Bool(b) => CstInputValue::Bool(b),
        serde_json::Value::Number(n) => CstInputValue::Number(n.to_string()),
        serde_json::Value::String(s) => CstInputValue::String(s),
        serde_json::Value::Array(arr) => {
            CstInputValue::Array(arr.into_iter().map(serde_to_cst_input).collect())
        }
        serde_json::Value::Object(map) => {
            let props: Vec<(String, CstInputValue)> = map
                .into_iter()
                .map(|(k, v)| (k, serde_to_cst_input(v)))
                .collect();
            CstInputValue::Object(props)
        }
    }
}

/// Insert or replace hook entries in the raw JSONC string.
///
/// For each `(event_type, entry_value)` pair:
/// - If the `hooks[event_type]` array exists and already contains an entry with
///   `_openlatch: true`, that entry is **replaced** (idempotent re-install).
/// - Otherwise, the new entry is **appended** to the array (creating the array
///   and/or `hooks` object if they do not yet exist).
///
/// The returned string preserves all comments, whitespace, and trailing commas
/// in regions not modified by this function.
///
/// # Errors
///
/// - `OL-1402` if the JSONC cannot be parsed.
pub fn insert_hook_entries(
    raw_jsonc: &str,
    entries: &[(String, serde_json::Value)],
) -> Result<(String, Vec<super::HookAction>), OlError> {
    use jsonc_parser::cst::{CstContainerNode, CstNode, CstRootNode};
    use jsonc_parser::ParseOptions;

    // Parse the JSONC to a CST.
    let root = CstRootNode::parse(raw_jsonc, &ParseOptions::default()).map_err(|e| {
        OlError::new(
            ERR_HOOK_MALFORMED_JSONC,
            format!("Cannot parse settings.json as JSONC: {e}"),
        )
        .with_suggestion("Fix the JSON syntax in your settings.json file.")
        .with_docs("https://docs.openlatch.ai/errors/OL-1402")
    })?;

    // Get (or create) the root object.
    let root_obj = root.object_value_or_set();

    // Ensure "hooks" key exists as an object.
    let hooks_obj = root_obj.object_value_or_set("hooks");

    let mut actions = Vec::new();

    for (event_type, entry_value) in entries {
        // Ensure the event-type array exists.
        let arr = hooks_obj.array_value_or_set(event_type);

        // Convert the new entry to a CstInputValue (object form).
        let cst_value = serde_to_cst_input(entry_value.clone());

        // Search for an existing OpenLatch-owned element.
        let existing_index = find_openlatch_element_index(&arr);

        if let Some(idx) = existing_index {
            // Replace the existing element.  The CST array's elements() are CstNode;
            // Container nodes have replace_with(), leaf nodes have replace_with() too.
            let elements = arr.elements();
            let old_el = &elements[idx];
            match old_el {
                CstNode::Container(c) => {
                    // object or array — replace using container's replace_with
                    match c {
                        CstContainerNode::Object(obj) => {
                            obj.clone().replace_with(cst_value);
                        }
                        CstContainerNode::Array(a) => {
                            a.clone().replace_with(cst_value);
                        }
                        _ => {
                            // Unexpected container type — fall back to remove + insert
                            old_el.clone().remove();
                            arr.insert(idx, cst_value);
                        }
                    }
                }
                CstNode::Leaf(_) => {
                    // scalar value — remove and re-insert
                    old_el.clone().remove();
                    arr.insert(idx, cst_value);
                }
            }
            actions.push(super::HookAction::Replaced);
        } else {
            // Append a new element.
            arr.append(cst_value);
            actions.push(super::HookAction::Added);
        }
    }

    Ok((root.to_string(), actions))
}

/// Insert or replace hook entries on an already-parsed CST root.
///
/// Same logic as [`insert_hook_entries`] but operates on the CST directly,
/// so callers like [`super::atomic::atomic_rewrite_jsonc`] can batch
/// multiple mutations before a single serialise + write.
pub fn insert_hook_entries_cst(
    root: &jsonc_parser::cst::CstRootNode,
    entries: &[(String, serde_json::Value)],
) -> Result<Vec<super::HookAction>, OlError> {
    use jsonc_parser::cst::CstNode;

    let root_obj = root.object_value_or_set();
    let hooks_obj = root_obj.object_value_or_set("hooks");

    let mut actions = Vec::new();

    for (event_type, entry_value) in entries {
        let arr = hooks_obj.array_value_or_set(event_type);

        // Remove every existing openlatch-owned entry: both marked entries
        // and orphans (entries whose command references openlatch-hook but
        // lack the _openlatch marker — leftovers from pre-marker installs).
        let to_remove: Vec<CstNode> = arr
            .elements()
            .into_iter()
            .filter(is_openlatch_owned_node)
            .collect();

        let had_existing = !to_remove.is_empty();
        for el in to_remove {
            el.remove();
        }

        let cst_value = serde_to_cst_input(entry_value.clone());
        arr.append(cst_value);

        actions.push(if had_existing {
            super::HookAction::Replaced
        } else {
            super::HookAction::Added
        });
    }

    Ok(actions)
}

/// Return `true` if the CST node is an OpenLatch-owned hook entry — either
/// marked with `_openlatch` or an orphan whose command references the
/// `openlatch-hook` binary. Orphan detection handles pre-marker installs
/// where a previous version left unmarked entries behind.
fn is_openlatch_owned_node(el: &jsonc_parser::cst::CstNode) -> bool {
    if is_openlatch_node(el) {
        return true;
    }
    match el.to_serde_value() {
        Some(serde_json::Value::Object(map)) => map
            .get("hooks")
            .and_then(|h| h.as_array())
            .map(|arr| {
                arr.iter().any(|h| {
                    h.get("command")
                        .and_then(|c| c.as_str())
                        .is_some_and(|s| s.contains("openlatch-hook"))
                })
            })
            .unwrap_or(false),
        _ => false,
    }
}

/// Set an environment variable on an already-parsed CST root.
pub fn set_env_var_cst(
    root: &jsonc_parser::cst::CstRootNode,
    key: &str,
    value: &str,
) -> Result<(), OlError> {
    let root_obj = root.object_value_or_set();
    let env_obj = root_obj.object_value_or_set("env");
    let string_value = jsonc_parser::cst::CstInputValue::String(value.to_string());
    if let Some(prop) = env_obj.get(key) {
        prop.set_value(string_value);
    } else {
        env_obj.append(key, string_value);
    }
    Ok(())
}

/// Remove all OpenLatch-owned entries on an already-parsed CST root.
pub fn remove_owned_entries_cst(root: &jsonc_parser::cst::CstRootNode) -> Result<(), OlError> {
    use jsonc_parser::cst::{CstContainerNode, CstNode};

    let root_obj = match root.object_value() {
        Some(obj) => obj,
        None => return Ok(()),
    };

    let hooks_prop = match root_obj.get("hooks") {
        Some(p) => p,
        None => return Ok(()),
    };

    let hooks_obj = match hooks_prop.value() {
        Some(CstNode::Container(CstContainerNode::Object(obj))) => obj,
        _ => return Ok(()),
    };

    for event_prop in hooks_obj.properties() {
        let arr = match event_prop.value() {
            Some(CstNode::Container(CstContainerNode::Array(a))) => a,
            _ => continue,
        };

        let to_remove: Vec<CstNode> = arr
            .elements()
            .into_iter()
            .filter(is_openlatch_node)
            .collect();

        for el in to_remove {
            el.remove();
        }
    }

    Ok(())
}

/// Remove all hook entries owned by OpenLatch (`_openlatch: true`) from the JSONC.
///
/// Entries belonging to other tools are left untouched.
///
/// # Errors
///
/// - `OL-1402` if the JSONC cannot be parsed.
pub fn remove_owned_entries(raw_jsonc: &str) -> Result<String, OlError> {
    use jsonc_parser::cst::{CstContainerNode, CstNode, CstRootNode};
    use jsonc_parser::ParseOptions;

    let root = CstRootNode::parse(raw_jsonc, &ParseOptions::default()).map_err(|e| {
        OlError::new(
            ERR_HOOK_MALFORMED_JSONC,
            format!("Cannot parse settings.json as JSONC: {e}"),
        )
        .with_suggestion("Fix the JSON syntax in your settings.json file.")
        .with_docs("https://docs.openlatch.ai/errors/OL-1402")
    })?;

    // Walk the object tree; if there's no hooks key we're done.
    let root_obj = match root.object_value() {
        Some(obj) => obj,
        None => return Ok(root.to_string()),
    };

    let hooks_prop = match root_obj.get("hooks") {
        Some(p) => p,
        None => return Ok(root.to_string()),
    };

    let hooks_obj = match hooks_prop.value() {
        Some(CstNode::Container(CstContainerNode::Object(obj))) => obj,
        _ => return Ok(root.to_string()),
    };

    for event_prop in hooks_obj.properties() {
        let arr = match event_prop.value() {
            Some(CstNode::Container(CstContainerNode::Array(a))) => a,
            _ => continue,
        };

        // Collect elements to remove (snapshot before mutating).
        let to_remove: Vec<CstNode> = arr
            .elements()
            .into_iter()
            .filter(is_openlatch_node)
            .collect();

        // Remove each owned entry. The CST handles re-indexing internally.
        for el in to_remove {
            el.remove();
        }
    }

    Ok(root.to_string())
}

/// Parse JSONC settings into a `serde_json::Value`.
///
/// Loses comment/whitespace fidelity — callers should only use this for
/// read-only inspection (e.g. diagnostics), never as a step toward writing
/// the file back. For writes, use the CST-based helpers above so comments
/// and formatting survive.
///
/// # Errors
///
/// - `OL-1402` if the JSONC cannot be parsed.
pub fn parse_settings_value(raw_jsonc: &str) -> Result<serde_json::Value, OlError> {
    use jsonc_parser::cst::CstRootNode;
    use jsonc_parser::ParseOptions;

    let root = CstRootNode::parse(raw_jsonc, &ParseOptions::default()).map_err(|e| {
        OlError::new(
            ERR_HOOK_MALFORMED_JSONC,
            format!("Cannot parse settings.json as JSONC: {e}"),
        )
        .with_suggestion("Fix the JSON syntax in your settings.json file.")
        .with_docs("https://docs.openlatch.ai/errors/OL-1402")
    })?;
    root.to_serde_value().ok_or_else(|| {
        OlError::new(
            ERR_HOOK_MALFORMED_JSONC,
            "settings.json is empty or invalid",
        )
        .with_docs("https://docs.openlatch.ai/errors/OL-1402")
    })
}

/// Set an environment variable in the `"env"` object of the JSONC settings.
///
/// Creates the `"env"` key if it does not exist. Overwrites the value if the key
/// already exists. Preserves all other keys and JSONC structure.
///
/// # Errors
///
/// - `OL-1402` if the JSONC cannot be parsed.
pub fn set_env_var(raw_jsonc: &str, key: &str, value: &str) -> Result<String, OlError> {
    use jsonc_parser::cst::CstRootNode;
    use jsonc_parser::ParseOptions;

    let root = CstRootNode::parse(raw_jsonc, &ParseOptions::default()).map_err(|e| {
        OlError::new(
            ERR_HOOK_MALFORMED_JSONC,
            format!("Cannot parse settings.json as JSONC: {e}"),
        )
        .with_suggestion("Fix the JSON syntax in your settings.json file.")
        .with_docs("https://docs.openlatch.ai/errors/OL-1402")
    })?;

    let root_obj = root.object_value_or_set();
    let env_obj = root_obj.object_value_or_set("env");
    let string_value = jsonc_parser::cst::CstInputValue::String(value.to_string());
    if let Some(prop) = env_obj.get(key) {
        prop.set_value(string_value);
    } else {
        env_obj.append(key, string_value);
    }

    Ok(root.to_string())
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/// Find the index of the first array element that carries `"_openlatch": true`.
fn find_openlatch_element_index(arr: &jsonc_parser::cst::CstArray) -> Option<usize> {
    arr.elements().iter().position(is_openlatch_node)
}

/// Return `true` if the CST node is a JSON object carrying an OpenLatch
/// ownership marker — either the legacy `"_openlatch": true` boolean or
/// the tamper-evident `"_openlatch": { v, id, installed_at, hmac }` object.
fn is_openlatch_node(el: &jsonc_parser::cst::CstNode) -> bool {
    match el.to_serde_value() {
        Some(serde_json::Value::Object(map)) => matches!(
            map.get("_openlatch"),
            Some(serde_json::Value::Bool(true)) | Some(serde_json::Value::Object(_))
        ),
        _ => false,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    // -------------------------------------------------------------------------
    // read_or_create_settings tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_read_or_create_creates_missing_file() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("settings.json");

        // File does not exist yet.
        assert!(!path.exists());

        let content = read_or_create_settings(&path).unwrap();
        assert_eq!(content, "{}");
        assert!(path.exists());
    }

    #[test]
    fn test_read_or_create_reads_existing_file() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("settings.json");
        std::fs::write(&path, r#"{ "key": "value" }"#).unwrap();

        let content = read_or_create_settings(&path).unwrap();
        assert_eq!(content, r#"{ "key": "value" }"#);
    }

    // -------------------------------------------------------------------------
    // insert_hook_entries tests
    // -------------------------------------------------------------------------

    fn make_entries() -> Vec<(String, serde_json::Value)> {
        vec![
            (
                "PreToolUse".to_string(),
                json!({ "_openlatch": true, "matcher": "", "hooks": [] }),
            ),
            (
                "UserPromptSubmit".to_string(),
                json!({ "_openlatch": true, "hooks": [] }),
            ),
            (
                "Stop".to_string(),
                json!({ "_openlatch": true, "hooks": [] }),
            ),
        ]
    }

    #[test]
    fn test_insert_into_empty_settings_creates_hooks_object() {
        let raw = "{}";
        let entries = make_entries();

        let (result, actions) = insert_hook_entries(raw, &entries).unwrap();
        let parsed: serde_json::Value = serde_json::from_str(&result).unwrap();

        assert!(parsed["hooks"]["PreToolUse"].is_array());
        assert!(parsed["hooks"]["UserPromptSubmit"].is_array());
        assert!(parsed["hooks"]["Stop"].is_array());

        assert_eq!(parsed["hooks"]["PreToolUse"][0]["_openlatch"], true);
        assert_eq!(actions.len(), 3);
        assert!(actions
            .iter()
            .all(|a| *a == super::super::HookAction::Added));
    }

    #[test]
    fn test_insert_preserves_existing_non_openlatch_hooks() {
        let raw = r#"{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "echo hi" }] }
    ]
  }
}"#;
        let entries = vec![(
            "PreToolUse".to_string(),
            json!({ "_openlatch": true, "matcher": "", "hooks": [] }),
        )];

        let (result, _) = insert_hook_entries(raw, &entries).unwrap();
        let parsed: serde_json::Value = serde_json::from_str(&result).unwrap();

        let arr = parsed["hooks"]["PreToolUse"].as_array().unwrap();
        // Both the original entry and the OpenLatch entry should be present.
        assert_eq!(arr.len(), 2, "Expected 2 entries, got {}", arr.len());
        // Original entry still present.
        assert_eq!(arr[0]["hooks"][0]["command"], "echo hi");
        // OpenLatch entry appended.
        assert_eq!(arr[1]["_openlatch"], true);
    }

    #[test]
    fn test_insert_is_idempotent_replaces_existing_openlatch_entry() {
        let raw = r#"{
  "hooks": {
    "PreToolUse": [
      { "_openlatch": true, "matcher": "", "hooks": [{"type": "http", "url": "http://localhost:7443/hooks/pre-tool-use"}] }
    ]
  }
}"#;
        let new_entry = json!({
            "_openlatch": true,
            "matcher": "",
            "hooks": [{ "type": "http", "url": "http://localhost:9000/hooks/pre-tool-use" }]
        });
        let entries = vec![("PreToolUse".to_string(), new_entry)];

        let (result, actions) = insert_hook_entries(raw, &entries).unwrap();
        let parsed: serde_json::Value = serde_json::from_str(&result).unwrap();

        let arr = parsed["hooks"]["PreToolUse"].as_array().unwrap();
        // Must still be exactly one entry.
        assert_eq!(
            arr.len(),
            1,
            "Idempotent install should not duplicate entries"
        );
        // The URL should be updated.
        let url = arr[0]["hooks"][0]["url"].as_str().unwrap();
        assert!(url.contains("9000"), "Expected updated URL, got: {url}");
        assert_eq!(actions[0], super::super::HookAction::Replaced);
    }

    #[test]
    fn test_insert_preserves_jsonc_comments() {
        // Comments in untouched regions (other arrays, other keys) should survive.
        let raw_with_comment = r#"{
  "hooks": {
    "Stop": [
      // existing user hook
      { "type": "command", "command": "echo stop" }
    ]
  }
}"#;
        let entries = vec![(
            "PreToolUse".to_string(),
            json!({ "_openlatch": true, "matcher": "", "hooks": [] }),
        )];

        let (result, _) = insert_hook_entries(raw_with_comment, &entries).unwrap();
        // The comment in the Stop array should survive (untouched region).
        assert!(
            result.contains("// existing user hook"),
            "Comment was removed: {result}"
        );

        // Verify the new entry was added by re-parsing via the JSONC parser
        // (not serde_json which rejects JSONC comments).
        use jsonc_parser::cst::CstRootNode;
        use jsonc_parser::ParseOptions;
        let verify_root = CstRootNode::parse(&result, &ParseOptions::default())
            .expect("result must be valid JSONC");
        let root_obj = verify_root.object_value().expect("root must be object");
        let hooks_obj = root_obj
            .object_value("hooks")
            .expect("hooks key must exist");
        let pre_arr = hooks_obj
            .array_value("PreToolUse")
            .expect("PreToolUse must be array");
        // The first element should carry _openlatch:true
        let first_el = pre_arr
            .elements()
            .into_iter()
            .next()
            .expect("must have element");
        let first_val = first_el.to_serde_value().expect("must be a value");
        assert_eq!(first_val["_openlatch"], json!(true));
    }

    #[test]
    fn test_malformed_jsonc_returns_ol_1402() {
        let raw = "{ this is not json }";
        let entries = make_entries();

        let err = insert_hook_entries(raw, &entries).unwrap_err();
        assert_eq!(err.code, ERR_HOOK_MALFORMED_JSONC);
    }

    // -------------------------------------------------------------------------
    // remove_owned_entries tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_remove_owned_entries_removes_openlatch_entries() {
        let raw = r#"{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "echo hi" }] },
      { "_openlatch": true, "matcher": "", "hooks": [] }
    ]
  }
}"#;
        let result = remove_owned_entries(raw).unwrap();
        let parsed: serde_json::Value = serde_json::from_str(&result).unwrap();

        let arr = parsed["hooks"]["PreToolUse"].as_array().unwrap();
        // Only the non-OpenLatch entry should remain.
        assert_eq!(
            arr.len(),
            1,
            "Expected 1 entry after removal, got {}",
            arr.len()
        );
        assert!(arr[0].get("_openlatch").is_none());
    }

    #[test]
    fn test_remove_owned_entries_no_hooks_key_is_noop() {
        let raw = r#"{"key": "value"}"#;
        let result = remove_owned_entries(raw).unwrap();
        let parsed: serde_json::Value = serde_json::from_str(&result).unwrap();
        assert_eq!(parsed["key"], "value");
        assert!(parsed.get("hooks").is_none());
    }
}