forge_workspace/

settings_write.rs

//! The comment-preserving writer behind the settings editor.
//!
//! An edit names a catalogue pattern and the concrete path it fills; the
//! pattern says where the item sits, so a display path with dots in a name
//! is never re-parsed as TOML. One pass applies every edit to the current
//! text, and the caller validates the candidate with the boot loader before
//! it replaces the file.

use forge_primitives::settings::{
    EditKind, SettingsDocument, SettingsEdit, SettingsEditOp, SettingsEditRequest, SettingsKey,
};
use toml_edit::{Array, ArrayOfTables, DocumentMut, InlineTable, Item, Table, Value};

/// Why an edit could not be applied.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct WriteError {
    /// The loader-facing words, and the key to anchor them at where one is
    /// known.
    pub message: String,
    pub key_path: Option<String>,
}

fn invalid(message: impl Into<String>, key_path: Option<String>) -> WriteError {
    WriteError { message: message.into(), key_path }
}

/// Apply every edit to the current text.
pub(crate) fn apply(
    current: &str,
    edits: &[SettingsEditRequest],
    document: &SettingsDocument,
) -> Result<String, WriteError> {
    // **One path, one edit.** Two edits for one key have no defined winner,
    // and the second would silently undo the first while the save reported a
    // change; the batch is refused rather than guessed at.
    let mut named = std::collections::HashSet::with_capacity(edits.len());
    for edit in edits {
        if !named.insert(edit.key_path.as_str()) {
            return Err(invalid(
                format!(
                    "`{}` appears twice in one save; a batch names each key once",
                    edit.key_path,
                ),
                Some(edit.key_path.clone()),
            ));
        }
    }
    let mut doc: DocumentMut = current
        .parse()
        .map_err(|error| invalid(format!("the current file does not parse: {error}"), None))?;
    // **A rename is applied last.** Locating an entry by its pre-edit name
    // (an org's, a project's, an account's) fails once that name moved, so a
    // batch that renames and edits the same entry applies the edits first.
    // A project's rename goes before its org's: the project's own identity is
    // the org's pre-edit name.
    let mut rest: Vec<&SettingsEditRequest> = Vec::new();
    let mut nested_renames: Vec<&SettingsEditRequest> = Vec::new();
    let mut entry_renames: Vec<&SettingsEditRequest> = Vec::new();
    for edit in edits {
        match identity_pattern(edit, document) {
            None => rest.push(edit),
            Some("orgs[].projects[].name") => nested_renames.push(edit),
            Some(_) => entry_renames.push(edit),
        }
    }
    for edit in rest {
        apply_one(&mut doc, edit, document)?;
    }
    for edit in nested_renames {
        apply_one(&mut doc, edit, document)?;
    }
    for edit in entry_renames {
        apply_one(&mut doc, edit, document)?;
    }
    let text = doc.to_string();
    // toml_edit renders `\n`; a CRLF file comes back as it went in, including
    // inside a multi-line string, where the newline is content rather than
    // layout. **The layout is read from the first newline**: a CRLF inside a
    // string in an otherwise LF file is content and must not decide it.
    let crlf = current
        .find('\n')
        .is_some_and(|at| at > 0 && current.as_bytes().get(at - 1) == Some(&b'\r'));
    Ok(if crlf { text.replace("\r\n", "\n").replace('\n', "\r\n") } else { text })
}

/// The catalogue pattern of an edit when it is one of the fields that names
/// its entry, which a batch must apply after the edit's other changes.
fn identity_pattern<'a>(
    edit: &'a SettingsEditRequest,
    document: &'a SettingsDocument,
) -> Option<&'a str> {
    let pattern = if edit.pattern.is_empty() {
        find_key(document, &edit.key_path).map(|key| key.pattern.as_str())?
    } else {
        edit.pattern.as_str()
    };
    matches!(
        pattern,
        "orgs[].name" | "orgs[].projects[].name" | "accounts[].display_name" | "slack[].workspace"
    )
    .then_some(pattern)
}

fn apply_one(
    doc: &mut DocumentMut,
    edit: &SettingsEditRequest,
    document: &SettingsDocument,
) -> Result<(), WriteError> {
    match edit.op {
        SettingsEditOp::Set => set_key(doc, edit, document),
        SettingsEditOp::Remove if edit.pattern.is_empty() => remove_entry(doc, edit),
        SettingsEditOp::Remove => remove_key(doc, edit, document),
        SettingsEditOp::Add => add_entry(doc, edit),
    }
}

fn find_key<'a>(document: &'a SettingsDocument, path: &str) -> Option<&'a SettingsKey> {
    document.areas.iter().flat_map(|area| &area.keys).find(|key| key.path == path)
}

fn set_key(
    doc: &mut DocumentMut,
    edit: &SettingsEditRequest,
    document: &SettingsDocument,
) -> Result<(), WriteError> {
    let absent;
    let key: &SettingsKey = match find_key(document, &edit.key_path) {
        Some(found) => {
            if !edit.pattern.is_empty() && edit.pattern != found.pattern {
                return Err(invalid(
                    format!("`{}` is not the key it was loaded as", edit.key_path),
                    Some(edit.key_path.clone()),
                ));
            }
            found
        }
        // **An optional key the config does not set emits no row.** The
        // edit carries the catalogue pattern that would create it, and the
        // writer locates from the pattern rather than the missing row.
        None if !edit.pattern.is_empty() => {
            absent =
                crate::settings::synthetic_key(&edit.key_path, &edit.pattern).ok_or_else(|| {
                    invalid(
                        format!("`{}` is not a catalogue key", edit.key_path),
                        Some(edit.key_path.clone()),
                    )
                })?;
            &absent
        }
        None => {
            return Err(invalid(
                format!("`{}` is no longer in this config", edit.key_path),
                Some(edit.key_path.clone()),
            ));
        }
    };
    let value = edit.value.clone().unwrap_or(serde_json::Value::Null);
    if value.is_null() {
        return remove_leaf(doc, key);
    }
    let toml = to_toml(&value, key.edit.kind, &key.edit.allowed, &edit.key_path)?;
    let (steps, leaf) = locate(key).ok_or_else(|| {
        invalid(
            format!("`{}` does not fill its catalogue pattern", edit.key_path),
            Some(edit.key_path.clone()),
        )
    })?;
    let parent = descend(doc, &steps, true).ok_or_else(|| {
        invalid(
            format!("`{}` has no table to write into", edit.key_path),
            Some(edit.key_path.clone()),
        )
    })?;
    parent.set(&leaf, toml);
    Ok(())
}

fn remove_key(
    doc: &mut DocumentMut,
    edit: &SettingsEditRequest,
    document: &SettingsDocument,
) -> Result<(), WriteError> {
    let key = find_key(document, &edit.key_path).ok_or_else(|| {
        invalid(
            format!("`{}` is no longer in this config", edit.key_path),
            Some(edit.key_path.clone()),
        )
    })?;
    remove_leaf(doc, key)
}

fn remove_leaf(doc: &mut DocumentMut, key: &SettingsKey) -> Result<(), WriteError> {
    let (steps, leaf) = locate(key).ok_or_else(|| {
        invalid(
            format!("`{}` does not fill its catalogue pattern", key.path),
            Some(key.path.clone()),
        )
    })?;
    let parent = descend(doc, &steps, false).ok_or_else(|| {
        invalid(format!("`{}` has no table to remove from", key.path), Some(key.path.clone()))
    })?;
    let leftover = parent.remove(&leaf);
    // The key was the table's last; its comments belong at the table's end.
    if let Some(prefix) = leftover
        && let Some(Container::Table(table)) = descend(doc, &steps, false)
    {
        keep_suffix(table, &prefix);
    }
    Ok(())
}

/// One step into the document.
#[derive(Clone, Debug, PartialEq, Eq)]
enum Step {
    Key(String),
    Account(String),
    Org(String),
    Project(String),
    Slack(String),
}

/// Where a leaf sits: the steps to its parent and the leaf's own key.
///
/// **The row's own instance names are tried first, then the path's own
/// split.** `group` holds the names the row was built from, but `split_row`
/// cannot tell a name from a key segment: projects `api` and `api.handoff`
/// both match the row `orgs.Acme.projects.api.handoff.enabled`, and its
/// longest-name rule picks the sibling. So a group split is used only when
/// it reassembles the row's path exactly, and the fallback reads the path
/// against the pattern's literal segments.
fn locate(key: &SettingsKey) -> Option<(Vec<Step>, String)> {
    let parts = parts_of(&key.pattern)?;
    if let Some(found) = locate_from_group(key, &parts) {
        return Some(found);
    }
    locate_from_path(key, &parts)
}

/// The split from the row's `group`, accepted only when it rebuilds the row's
/// own path.
fn locate_from_group(key: &SettingsKey, parts: &[Part]) -> Option<(Vec<Step>, String)> {
    // `group` also carries a table name for the areas whose rows sit under
    // one (`slack[].token` groups as `["slack", workspace]`, `server.port`
    // as `["server"]`), so the names a wildcard takes are its LAST entries.
    let consuming = parts
        .iter()
        .take(parts.len().saturating_sub(1))
        .filter(|part| matches!(part, Part::Array(_) | Part::Wildcard))
        .count();
    let start = key.group.len().checked_sub(consuming)?;
    let names: Vec<String> = key.group[start..].to_vec();
    let (steps, leaf, rebuilt) = build(parts, &names, &key.leaf)?;
    (rebuilt == key.path).then_some((steps, leaf))
}

/// The split read off the row's path: each wildcard takes the shortest name
/// that lets the rest of the pattern match, so the pattern's literal
/// segments anchor it.
fn locate_from_path(key: &SettingsKey, parts: &[Part]) -> Option<(Vec<Step>, String)> {
    let mut names = Vec::new();
    if !match_path(parts, &key.path, &mut names) {
        return None;
    }
    let (steps, leaf, rebuilt) = build(parts, &names, &key.leaf)?;
    (rebuilt == key.path).then_some((steps, leaf))
}

/// Turn one set of instance names into steps, and rebuild the path they
/// should produce.
fn build(parts: &[Part], names: &[String], leaf_hint: &str) -> Option<(Vec<Step>, String, String)> {
    let last = parts.last()?;
    let leaf = match last {
        Part::Wildcard => leaf_hint.to_owned(),
        Part::Literal(value) | Part::Array(value) => value.clone(),
    };
    let mut next = names.iter();
    let mut steps = Vec::new();
    let mut rebuilt = String::new();
    for (index, part) in parts.iter().enumerate() {
        if index > 0 {
            rebuilt.push('.');
        }
        match part {
            Part::Literal(value) => {
                rebuilt.push_str(value);
                // The last literal is the leaf itself, which `build` returns.
                if index + 1 < parts.len() {
                    steps.push(Step::Key(value.clone()));
                }
            }
            Part::Array(table) => {
                rebuilt.push_str(table);
                if index + 1 == parts.len() {
                    continue;
                }
                rebuilt.push('.');
                let name = next.next()?;
                rebuilt.push_str(name);
                steps.push(array_step(table, name)?);
            }
            Part::Wildcard => {
                if index + 1 == parts.len() {
                    rebuilt.push_str(&leaf);
                } else {
                    let name = next.next()?;
                    rebuilt.push_str(name);
                    steps.push(Step::Key(name.clone()));
                }
            }
        }
    }
    if next.next().is_some() {
        return None;
    }
    Some((steps, leaf, rebuilt))
}

fn array_step(table: &str, name: &str) -> Option<Step> {
    Some(match table {
        "accounts" => Step::Account(name.to_owned()),
        "orgs" => Step::Org(name.to_owned()),
        "projects" => Step::Project(name.to_owned()),
        "slack" => Step::Slack(name.to_owned()),
        _ => return None,
    })
}

/// Whether `path` fills `pattern`, and the instance names it took. The
/// catalogue's own matcher, so a key the config does not set can still be
/// resolved back to the pattern that would write it.
pub(crate) fn match_pattern(pattern: &str, path: &str) -> Option<Vec<String>> {
    let parts = parts_of(pattern)?;
    let mut names = Vec::new();
    match_path(&parts, path, &mut names).then_some(names)
}

/// Match a pattern against a display path, shortest wildcard names first, and
/// collect the instance names in wildcard order.
fn match_path(parts: &[Part], path: &str, names: &mut Vec<String>) -> bool {
    let Some((part, rest)) = parts.split_first() else {
        return path.is_empty();
    };
    match part {
        Part::Literal(value) => {
            if rest.is_empty() {
                return path == value;
            }
            path.strip_prefix(value)
                .and_then(|tail| tail.strip_prefix('.'))
                .is_some_and(|tail| match_path(rest, tail, names))
        }
        Part::Array(table) => {
            if rest.is_empty() {
                return path == table;
            }
            let Some(tail) = path.strip_prefix(table).and_then(|tail| tail.strip_prefix('.'))
            else {
                return false;
            };
            split_then(tail, names, rest)
        }
        // A trailing wildcard is the leaf, which `build` takes from the row;
        // the rebuilt path is what checks it.
        Part::Wildcard => rest.is_empty() || split_then(path, names, rest),
    }
}

/// Try each dot boundary of `path` as a wildcard name, shortest first, and
/// keep the name only when the rest of the pattern matches.
fn split_then(path: &str, names: &mut Vec<String>, rest: &[Part]) -> bool {
    for (at, ch) in path.char_indices() {
        if ch != '.' || at == 0 {
            continue;
        }
        names.push(path[..at].to_owned());
        if match_path(rest, &path[at + 1..], names) {
            return true;
        }
        names.pop();
    }
    false
}

#[derive(Clone, Debug)]
enum Part {
    Literal(String),
    /// `name[]`: the table's name and one wildcard for the instance.
    Array(String),
    Wildcard,
}

fn parts_of(pattern: &str) -> Option<Vec<Part>> {
    let mut parts = Vec::new();
    for segment in pattern.split('.') {
        if segment.is_empty() {
            return None;
        }
        if segment == "*" {
            parts.push(Part::Wildcard);
        } else if let Some(name) = segment.strip_suffix("[]") {
            parts.push(Part::Array(name.to_owned()));
        } else {
            parts.push(Part::Literal(segment.to_owned()));
        }
    }
    (!parts.is_empty()).then_some(parts)
}

/// The container a leaf's parent is: a table, or an inline table
/// (`model_slugs = { ... }`).
enum Container<'a> {
    Table(&'a mut Table),
    Inline(&'a mut InlineTable),
}

impl Container<'_> {
    fn set(self, key: &str, value: Value) {
        match self {
            Self::Table(table) => match table.get_mut(key) {
                Some(item) => set_item_value(item, value),
                None => {
                    table.insert(key, Item::Value(value));
                }
            },
            Self::Inline(table) => match table.get_mut(key) {
                Some(existing) => {
                    let decor = existing.decor().clone();
                    let mut value = value;
                    *value.decor_mut() = decor;
                    *existing = value;
                }
                None => {
                    table.insert(key, value);
                }
            },
        }
    }

    /// Remove a key, moving its comments onto the next key in the table.
    /// When there is no next key the comments are handed back, because
    /// whether the table's own suffix renders depends on the table: an
    /// implicit `[models]` parent never renders one.
    fn remove(self, key: &str) -> Option<String> {
        match self {
            Self::Table(table) => {
                // **A key's comments live in its decor prefix**, so removing
                // the key must move them rather than delete them: onto the
                // key that follows it, or the table's own trailing text when
                // it was the last one.
                let next = next_key_after(table, key);
                // Read the leading text before the removal: a comment above
                // a key lives on the key's own leaf decor, one above a
                // sub-table's header on the table's own decor, and a trailing
                // one on the value's suffix.
                let prefix = table.get_key_value(key).map(|(held, item)| {
                    let mut text = String::new();
                    if let Item::Table(inner) = item
                        && let Some(raw) = inner.decor().prefix().and_then(|raw| raw.as_str())
                    {
                        text.push_str(raw);
                    }
                    text.push_str(&key_text(held));
                    let suffix = item_suffix(item);
                    if !suffix.trim().is_empty() {
                        if !text.is_empty() && !text.ends_with('\n') {
                            text.push('\n');
                        }
                        text.push_str(suffix.trim_start());
                        if !text.ends_with('\n') {
                            text.push('\n');
                        }
                    }
                    text
                });
                let removed = table.remove(key);
                let prefix = prefix?;
                if removed.is_none() || prefix.trim().is_empty() {
                    return None;
                }
                if let Some((mut next, _)) = next.and_then(|next| table.get_key_value_mut(&next)) {
                    let existing = next
                        .leaf_decor()
                        .prefix()
                        .and_then(|raw| raw.as_str())
                        .map(str::to_owned)
                        .unwrap_or_default();
                    next.leaf_decor_mut().set_prefix(format!("{prefix}{existing}"));
                    return None;
                }
                Some(prefix)
            }
            Self::Inline(table) => {
                table.remove(key);
                None
            }
        }
    }
}

/// The key after `key` in the table's own order, before it is removed.
fn next_key_after(table: &Table, key: &str) -> Option<String> {
    let mut seen = false;
    for (candidate, _) in table {
        if seen {
            return Some(candidate.to_owned());
        }
        if candidate == key {
            seen = true;
        }
    }
    None
}

/// The comments and whitespace a table entry's key carries before it.
fn key_text(key: &toml_edit::Key) -> String {
    key.leaf_decor().prefix().and_then(|raw| raw.as_str()).map(str::to_owned).unwrap_or_default()
}

/// The trailing comment a value carries on its own line.
fn item_suffix(item: &Item) -> String {
    match item {
        Item::Value(value) => value
            .decor()
            .suffix()
            .and_then(|raw| raw.as_str())
            .map(str::to_owned)
            .unwrap_or_default(),
        _ => String::new(),
    }
}

/// Remove one table from an array of tables, moving its comments onto the
/// entry that follows (or the previous entry's trailing text when it was
/// last) so a removal does not take the reader's notes with it. A prefix
/// with nowhere to go - the array's only entry - is handed back for the
/// parent table to carry.
fn remove_entry_at(array: &mut ArrayOfTables, index: usize) -> Option<String> {
    let prefix = array
        .get(index)
        .and_then(|table| table.decor().prefix().and_then(|raw| raw.as_str()).map(str::to_owned));
    let Some(prefix) = prefix.filter(|text| !text.trim().is_empty()) else {
        array.remove(index);
        return None;
    };
    array.remove(index);
    if let Some(next) = array.get_mut(index) {
        let existing = next
            .decor()
            .prefix()
            .and_then(|raw| raw.as_str())
            .map(str::to_owned)
            .unwrap_or_default();
        next.decor_mut().set_prefix(format!("{prefix}{existing}"));
        return None;
    }
    if index > 0
        && let Some(previous) = array.get_mut(index - 1)
    {
        let existing = previous
            .decor()
            .suffix()
            .and_then(|raw| raw.as_str())
            .map(str::to_owned)
            .unwrap_or_default();
        previous.decor_mut().set_suffix(format!("{existing}{prefix}"));
        return None;
    }
    Some(prefix)
}

/// Put a leftover entry's comments at the end of the table that held the
/// array, so an only-entry removal keeps them.
fn keep_prefix(table: &mut Table, prefix: Option<String>) {
    if let Some(prefix) = prefix {
        keep_suffix(table, &prefix);
    }
}

/// Append text to a table's own trailing decor.
fn keep_suffix(table: &mut Table, prefix: &str) {
    let existing =
        table.decor().suffix().and_then(|raw| raw.as_str()).map(str::to_owned).unwrap_or_default();
    table.decor_mut().set_suffix(format!("{existing}{prefix}"));
}

/// Put a departed table's comments above the next root entry, or at the
/// document's end when it was the last one.
fn place_root_prefix(doc: &mut DocumentMut, next: Option<String>, prefix: &str) {
    if prefix.trim().is_empty() {
        return;
    }
    if let Some(next) = next
        && let Some((mut key, _)) = doc.as_table_mut().get_key_value_mut(&next)
    {
        let existing = key
            .leaf_decor()
            .prefix()
            .and_then(|raw| raw.as_str())
            .map(str::to_owned)
            .unwrap_or_default();
        key.leaf_decor_mut().set_prefix(format!("{prefix}{existing}"));
        return;
    }
    let root = doc.as_table_mut();
    let existing =
        root.decor().suffix().and_then(|raw| raw.as_str()).map(str::to_owned).unwrap_or_default();
    root.decor_mut().set_suffix(format!("{existing}{prefix}"));
}

fn set_item_value(item: &mut Item, value: Value) {
    match item {
        Item::Value(existing) => {
            let decor = existing.decor().clone();
            let mut value = value;
            *value.decor_mut() = decor;
            *existing = value;
        }
        _ => *item = Item::Value(value),
    }
}

fn descend<'a>(doc: &'a mut DocumentMut, steps: &[Step], create: bool) -> Option<Container<'a>> {
    descend_from(Container::Table(doc.as_table_mut()), steps, create)
}

fn descend_from<'a>(
    container: Container<'a>,
    steps: &[Step],
    create: bool,
) -> Option<Container<'a>> {
    let Some((step, rest)) = steps.split_first() else { return Some(container) };
    let next: Container<'a> = match step {
        Step::Key(key) => match container {
            Container::Table(table) => {
                if create && table.get(key).is_none() {
                    table.insert(key, Item::Table(Table::new()));
                }
                match table.get_mut(key)? {
                    Item::Table(table) => Container::Table(table),
                    Item::Value(Value::InlineTable(table)) => Container::Inline(table),
                    _ => return None,
                }
            }
            Container::Inline(_) => return None,
        },
        Step::Account(name) => {
            let Container::Table(root) = container else { return None };
            let array = root.get_mut("accounts")?.as_array_of_tables_mut()?;
            let index = array
                .iter()
                .position(|table| table.get("display_name").and_then(Item::as_str) == Some(name))?;
            Container::Table(array.get_mut(index)?)
        }
        Step::Org(name) => {
            let Container::Table(root) = container else { return None };
            let array = root.get_mut("orgs")?.as_array_of_tables_mut()?;
            let index = array
                .iter()
                .position(|table| table.get("name").and_then(Item::as_str) == Some(name))?;
            Container::Table(array.get_mut(index)?)
        }
        Step::Slack(name) => {
            let Container::Table(root) = container else { return None };
            let array = root.get_mut("slack")?.as_array_of_tables_mut()?;
            let index = array
                .iter()
                .position(|table| table.get("workspace").and_then(Item::as_str) == Some(name))?;
            Container::Table(array.get_mut(index)?)
        }
        Step::Project(name) => {
            let Container::Table(org) = container else { return None };
            let array = org.get_mut("projects")?.as_array_of_tables_mut()?;
            let index = array
                .iter()
                .position(|table| table.get("name").and_then(Item::as_str) == Some(name))?;
            Container::Table(array.get_mut(index)?)
        }
    };
    descend_from(next, rest, create)
}

/// Validate one value against a key's edit spec without applying it, so a
/// tool can refuse a wrong type before it asks the reader anything.
pub(crate) fn validate(
    value: &serde_json::Value,
    edit: &SettingsEdit,
    path: &str,
) -> Result<(), WriteError> {
    to_toml(value, edit.kind, &edit.allowed, path).map(|_| ())
}

/// Convert a JSON value to the TOML shape its edit kind names.
fn to_toml(
    value: &serde_json::Value,
    kind: EditKind,
    allowed: &[String],
    path: &str,
) -> Result<Value, WriteError> {
    let bad = |what: &str| invalid(format!("`{path}` wants {what}"), Some(path.to_owned()));
    match kind {
        EditKind::String => {
            let value = value.as_str().ok_or_else(|| bad("a string"))?;
            Ok(Value::from(value.to_owned()))
        }
        EditKind::Enum => {
            let value = value.as_str().ok_or_else(|| bad("one of its names"))?;
            if !allowed.iter().any(|name| name == value) {
                return Err(invalid(
                    format!("`{path}` accepts {}; `{value}` is not one", allowed.join(", ")),
                    Some(path.to_owned()),
                ));
            }
            Ok(Value::from(value.to_owned()))
        }
        EditKind::Number => {
            if let Some(number) = value.as_i64() {
                Ok(Value::from(number))
            } else if let Some(number) = value.as_u64() {
                i64::try_from(number).map(Value::from).map_err(|_| bad("a whole number"))
            } else {
                Err(bad("a whole number"))
            }
        }
        EditKind::Bool => {
            let value = value.as_bool().ok_or_else(|| bad("true or false"))?;
            Ok(Value::from(value))
        }
        EditKind::List => {
            let items = value.as_array().ok_or_else(|| bad("a list"))?;
            let mut array = Array::new();
            for item in items {
                let text = item.as_str().ok_or_else(|| bad("a list of strings"))?;
                array.push(Value::from(text.to_owned()));
            }
            Ok(Value::Array(array))
        }
    }
}

/// Apply an entry's fields to a fresh table.
fn entry_table(
    value: &serde_json::Value,
    name_field: Option<&str>,
    name: &str,
) -> Result<Table, WriteError> {
    let object = value
        .as_object()
        .ok_or_else(|| invalid("an entry is added with its fields", Some(name.to_owned())))?;
    let mut table = Table::new();
    for (key, held) in object {
        let Some(item) = json_item(held, key)? else { continue };
        table.insert(key, item);
    }
    if let Some(field) = name_field
        && table.get(field).is_none()
    {
        table.insert(field, Item::Value(Value::from(name.to_owned())));
    }
    Ok(table)
}

fn json_item(value: &serde_json::Value, path: &str) -> Result<Option<Item>, WriteError> {
    match value {
        serde_json::Value::Null => Ok(None),
        serde_json::Value::Bool(value) => Ok(Some(Item::Value(Value::from(*value)))),
        serde_json::Value::Number(number) => {
            if let Some(value) = number.as_i64() {
                Ok(Some(Item::Value(Value::from(value))))
            } else if let Some(value) = number.as_u64() {
                i64::try_from(value).map(|value| Some(Item::Value(Value::from(value)))).map_err(
                    |_| invalid(format!("`{path}` wants a whole number"), Some(path.to_owned())),
                )
            } else {
                Err(invalid(format!("`{path}` wants a whole number"), Some(path.to_owned())))
            }
        }
        serde_json::Value::String(value) => Ok(Some(Item::Value(Value::from(value.clone())))),
        serde_json::Value::Array(items) => {
            let mut array = Array::new();
            for item in items {
                let text = item.as_str().ok_or_else(|| {
                    invalid(format!("`{path}` wants a list of strings"), Some(path.to_owned()))
                })?;
                array.push(Value::from(text.to_owned()));
            }
            Ok(Some(Item::Value(Value::Array(array))))
        }
        serde_json::Value::Object(fields) => {
            let mut table = Table::new();
            for (key, held) in fields {
                if let Some(item) = json_item(held, key)? {
                    table.insert(key, item);
                }
            }
            Ok(Some(Item::Table(table)))
        }
    }
}

/// Add a whole entry: an account, a project under an org, a Slack workspace,
/// or a model table.
fn add_entry(doc: &mut DocumentMut, edit: &SettingsEditRequest) -> Result<(), WriteError> {
    let value = edit
        .value
        .as_ref()
        .ok_or_else(|| invalid("an entry is added with its fields", Some(edit.key_path.clone())))?;
    match edit.area.as_str() {
        "accounts" => {
            let name = strip_prefix(&edit.key_path, "accounts.").ok_or_else(|| {
                invalid("an account's path names the account", Some(edit.key_path.clone()))
            })?;
            let table = entry_table(value, Some("display_name"), name)?;
            let exists =
                doc.as_table().get("accounts").and_then(Item::as_array_of_tables).is_some_and(
                    |array| {
                        array.iter().any(|held| {
                            held.get("display_name").and_then(Item::as_str) == Some(name)
                        })
                    },
                );
            if exists {
                return Err(invalid(
                    format!("an account named `{name}` already exists"),
                    Some(edit.key_path.clone()),
                ));
            }
            let accounts = doc
                .as_table_mut()
                .entry("accounts")
                .or_insert(Item::ArrayOfTables(ArrayOfTables::default()));
            let array = accounts.as_array_of_tables_mut().ok_or_else(|| {
                invalid("`accounts` is not an array of tables", Some(edit.key_path.clone()))
            })?;
            array.push(table);
            Ok(())
        }
        "connectors" => {
            let name = strip_prefix(&edit.key_path, "slack.").ok_or_else(|| {
                invalid("a Slack entry's path names the workspace", Some(edit.key_path.clone()))
            })?;
            let table = entry_table(value, Some("workspace"), name)?;
            // **The entry's identity is the workspace its value names**, not
            // the path's tail: entry_table keeps a value that carries its own
            // `workspace`, and the exists check has to compare the same name
            // the file will hold.
            let identity = value.get("workspace").and_then(|held| held.as_str()).unwrap_or(name);
            let exists =
                doc.as_table().get("slack").and_then(Item::as_array_of_tables).is_some_and(
                    |array| {
                        array.iter().any(|held| {
                            held.get("workspace").and_then(Item::as_str) == Some(identity)
                        })
                    },
                );
            if exists {
                return Err(invalid(
                    format!("a Slack workspace named `{identity}` already exists"),
                    Some(edit.key_path.clone()),
                ));
            }
            let slack = doc
                .as_table_mut()
                .entry("slack")
                .or_insert(Item::ArrayOfTables(ArrayOfTables::default()));
            let array = slack.as_array_of_tables_mut().ok_or_else(|| {
                invalid("`slack` is not an array of tables", Some(edit.key_path.clone()))
            })?;
            array.push(table);
            Ok(())
        }
        "models" => {
            let name = strip_prefix(&edit.key_path, "models.").ok_or_else(|| {
                invalid("a model's path names the model", Some(edit.key_path.clone()))
            })?;
            let table = entry_table(value, None, name)?;
            let exists = doc
                .as_table()
                .get("models")
                .and_then(Item::as_table)
                .is_some_and(|models| models.contains_key(name));
            if exists {
                return Err(invalid(
                    format!("a model named `{name}` already exists"),
                    Some(edit.key_path.clone()),
                ));
            }
            let models = doc.as_table_mut().entry("models").or_insert(Item::Table(Table::new()));
            let models = models
                .as_table_mut()
                .ok_or_else(|| invalid("`models` is not a table", Some(edit.key_path.clone())))?;
            models.insert(name, Item::Table(table));
            Ok(())
        }
        "projects" => {
            let Some((org, project)) = project_path(doc, &edit.key_path) else {
                return Err(invalid(
                    "a project's path names its org and the project",
                    Some(edit.key_path.clone()),
                ));
            };
            let table = entry_table(value, Some("name"), &project)?;
            let orgs = doc
                .as_table_mut()
                .get_mut("orgs")
                .ok_or_else(|| invalid("this config has no orgs", Some(edit.key_path.clone())))?;
            let Item::ArrayOfTables(orgs) = orgs else {
                return Err(invalid(
                    "`orgs` is not an array of tables",
                    Some(edit.key_path.clone()),
                ));
            };
            let index = orgs
                .iter()
                .position(|table| table.get("name").and_then(Item::as_str) == Some(org.as_str()))
                .ok_or_else(|| {
                    invalid(format!("no org named `{org}`"), Some(edit.key_path.clone()))
                })?;
            let org_table = orgs
                .get_mut(index)
                .ok_or_else(|| invalid("the org went away", Some(edit.key_path.clone())))?;
            let projects = org_table
                .entry("projects")
                .or_insert(Item::ArrayOfTables(ArrayOfTables::default()));
            let array = projects.as_array_of_tables_mut().ok_or_else(|| {
                invalid("`projects` is not an array of tables", Some(edit.key_path.clone()))
            })?;
            let exists = array
                .iter()
                .any(|held| held.get("name").and_then(Item::as_str) == Some(project.as_str()));
            if exists {
                return Err(invalid(
                    format!("a project named `{project}` already exists under `{org}`"),
                    Some(edit.key_path.clone()),
                ));
            }
            array.push(table);
            Ok(())
        }
        area => {
            Err(invalid(format!("`{area}` does not add entries here"), Some(edit.key_path.clone())))
        }
    }
}

/// Remove a whole entry.
fn remove_entry(doc: &mut DocumentMut, edit: &SettingsEditRequest) -> Result<(), WriteError> {
    let not_found = || invalid("that entry is not in this file", Some(edit.key_path.clone()));
    match edit.area.as_str() {
        "accounts" => {
            let name = strip_prefix(&edit.key_path, "accounts.").ok_or_else(not_found)?;
            let accounts = doc
                .as_table_mut()
                .get_mut("accounts")
                .and_then(Item::as_array_of_tables_mut)
                .ok_or_else(not_found)?;
            let index = accounts
                .iter()
                .position(|table| table.get("display_name").and_then(Item::as_str) == Some(name))
                .ok_or_else(not_found)?;
            let left = remove_entry_at(accounts, index);
            keep_prefix(doc.as_table_mut(), left);
            Ok(())
        }
        "connectors" => {
            let name = strip_prefix(&edit.key_path, "slack.").ok_or_else(not_found)?;
            let slack = doc
                .as_table_mut()
                .get_mut("slack")
                .and_then(Item::as_array_of_tables_mut)
                .ok_or_else(not_found)?;
            let index = slack
                .iter()
                .position(|table| table.get("workspace").and_then(Item::as_str) == Some(name))
                .ok_or_else(not_found)?;
            let left = remove_entry_at(slack, index);
            keep_prefix(doc.as_table_mut(), left);
            Ok(())
        }
        "models" => {
            let name = strip_prefix(&edit.key_path, "models.").ok_or_else(not_found)?;
            let models = doc
                .as_table_mut()
                .get_mut("models")
                .and_then(Item::as_table_mut)
                .ok_or_else(not_found)?;
            // The comment above `[models.foo]` lives on that sub-table's own
            // decor, so the removal moves it like any other key's.
            let removed_comments = Container::Table(models).remove(name);
            let emptied =
                doc.as_table().get("models").and_then(Item::as_table).is_some_and(Table::is_empty);
            let next = next_key_after(doc.as_table(), "models");
            let mut prefix = removed_comments.unwrap_or_default();
            if emptied {
                // `[models]` may be an explicit header: its own comment lives
                // on the root key and the table's decor, and removing the
                // emptied key would take it.
                if let Some((key, item)) = doc.as_table().get_key_value("models") {
                    prefix.push_str(&key_text(key));
                    if let Item::Table(table) = item
                        && let Some(raw) = table.decor().prefix().and_then(|raw| raw.as_str())
                    {
                        prefix.push_str(raw);
                    }
                }
                doc.as_table_mut().remove("models");
            }
            // An implicit `[models]` never renders its suffix, so anything
            // freed - the last model's comment, or the header's - moves to
            // the next root entry (or the document's own end).
            place_root_prefix(doc, next, &prefix);
            Ok(())
        }
        "projects" => {
            let (org, project) = project_path(doc, &edit.key_path).ok_or_else(not_found)?;
            let orgs = doc
                .as_table_mut()
                .get_mut("orgs")
                .and_then(Item::as_array_of_tables_mut)
                .ok_or_else(not_found)?;
            let org_index = orgs
                .iter()
                .position(|table| table.get("name").and_then(Item::as_str) == Some(org.as_str()))
                .ok_or_else(not_found)?;
            let org_table = orgs.get_mut(org_index).ok_or_else(not_found)?;
            let projects = org_table
                .get_mut("projects")
                .and_then(Item::as_array_of_tables_mut)
                .ok_or_else(not_found)?;
            let index = projects
                .iter()
                .position(|table| {
                    table.get("name").and_then(Item::as_str) == Some(project.as_str())
                })
                .ok_or_else(not_found)?;
            let left = remove_entry_at(projects, index);
            if let Some(org_table) = doc
                .as_table_mut()
                .get_mut("orgs")
                .and_then(Item::as_array_of_tables_mut)
                .and_then(|orgs| orgs.get_mut(org_index))
            {
                keep_prefix(org_table, left);
            }
            Ok(())
        }
        _ => Err(not_found()),
    }
}

fn strip_prefix<'a>(path: &'a str, prefix: &str) -> Option<&'a str> {
    path.strip_prefix(prefix)
}

/// The org and project a project entry path names, matched against the
/// document's own org names: an org name containing dots (or the literal
/// `.projects.`) cannot be cut short by a split.
fn project_path(doc: &DocumentMut, path: &str) -> Option<(String, String)> {
    let rest = path.strip_prefix("orgs.")?;
    let orgs = doc.as_table().get("orgs")?.as_array_of_tables()?;
    // **An exact identity comes first.** A project named `Team.projects.api`
    // under org `Acme` and a project `api` under org `Acme.projects.Team`
    // spell the same path, so the document's own pairs decide before any
    // cut - only an entry that does not exist yet falls through to the
    // longest org the path parses against.
    for org_table in orgs {
        let Some(org) = org_table.get("name").and_then(Item::as_str) else { continue };
        let Some(projects) = org_table.get("projects").and_then(Item::as_array_of_tables) else {
            continue;
        };
        for project_table in projects {
            let Some(project) = project_table.get("name").and_then(Item::as_str) else { continue };
            if path == format!("orgs.{org}.projects.{project}") {
                return Some((org.to_owned(), project.to_owned()));
            }
        }
    }
    let mut best: Option<(String, String)> = None;
    for table in orgs {
        let Some(org) = table.get("name").and_then(Item::as_str) else { continue };
        let Some(tail) = rest.strip_prefix(org).and_then(|tail| tail.strip_prefix(".projects."))
        else {
            continue;
        };
        if best.as_ref().is_none_or(|(held, _)| org.len() > held.len()) {
            best = Some((org.to_owned(), tail.to_owned()));
        }
    }
    best
}

#[cfg(test)]
mod tests {
    use std::path::Path;

    use forge_primitives::settings::{SettingsDocument, SettingsEditOp, SettingsEditRequest};

    use super::*;

    /// A config with comments, two accounts, an org and its projects, and a
    /// model table, so an edit can be read against the text around it.
    const FIXTURE: &str = r#"# forge.toml - the fixture
[server]
# the socket's port
port = 8790  # a hand-written comment
bind = "127.0.0.1"

[models."deepseek-v4.1-flash"]
auto_compact_window = 983040

# the first account
[[accounts]]
display_name = "One"
provider = "anthropic"
token = "one-token"
models = ["deepseek-v4.1-flash"]
model_slugs = { "deepseek-v4.1-flash" = "deepseek/deepseek-v4.1-flash" }

[accounts.env]
FLAG = "1"

# the second account
[[accounts]]
display_name = "Two"
provider = "anthropic"
token = "two-token"
models = ["deepseek-v4.1-flash"]

[[orgs]]
name = "Acme.Corp"
accounts = ["One"]

[[orgs.projects]]
name = "api.v2"
path = "/tmp/api.v2"
model = "deepseek-v4.1-flash"
permission_mode = "auto"

[orgs.projects.env]
SECRET = "s"

[[orgs.projects]]
name = "site"
path = "/tmp/site"
model = "deepseek-v4.1-flash"

[[slack]]
workspace = "Work"
token = "xoxp-example"
"#;

    fn document(raw: &str) -> SettingsDocument {
        let config =
            crate::config::load_from_text(std::path::PathBuf::from("/tmp/forge.toml"), raw)
                .expect("the fixture loads");
        crate::settings::document(&config, "v", Path::new("/tmp/forge.toml"))
    }

    fn key(document: &SettingsDocument, path: &str) -> (String, String) {
        let found = document
            .areas
            .iter()
            .flat_map(|area| &area.keys)
            .find(|key| key.path == path)
            .unwrap_or_else(|| panic!("{path} has no row"));
        (found.pattern.clone(), found.path.clone())
    }

    fn set_edit(
        document: &SettingsDocument,
        path: &str,
        value: serde_json::Value,
    ) -> SettingsEditRequest {
        let (pattern, key_path) = key(document, path);
        let area = document
            .areas
            .iter()
            .find(|area| area.keys.iter().any(|key| key.path == path))
            .map(|area| area.id.clone())
            .expect("the key has an area");
        SettingsEditRequest { area, key_path, pattern, op: SettingsEditOp::Set, value: Some(value) }
    }

    fn entry_edit(
        area: &str,
        key_path: &str,
        op: SettingsEditOp,
        value: Option<serde_json::Value>,
    ) -> SettingsEditRequest {
        SettingsEditRequest {
            area: area.to_owned(),
            key_path: key_path.to_owned(),
            pattern: String::new(),
            op,
            value,
        }
    }

    /// The key's value is replaced, and every comment and every line that
    /// did not change stays exactly where it was.
    #[test]
    fn a_set_preserves_the_comments_and_the_order() {
        let raw = FIXTURE;
        let document = document(raw);
        let edit = set_edit(&document, "server.port", serde_json::json!(8791));
        let out = apply(raw, &[edit], &document).expect("the edit applies");
        assert!(out.contains("# forge.toml - the fixture"), "the top comment stayed: {out}");
        assert!(out.contains("# the socket's port"), "the key's comment stayed: {out}");
        assert!(out.contains("# a hand-written comment"), "the inline comment stayed: {out}");
        assert!(out.contains("port = 8791"), "the value moved: {out}");
        assert!(
            out.find("[server]") < out.find("[[accounts]]"),
            "the tables kept their order: {out}",
        );
    }

    /// A value of the wrong shape is refused before anything else is tried.
    #[test]
    fn a_string_is_refused_for_a_number() {
        let document = document(FIXTURE);
        let edit = set_edit(&document, "server.port", serde_json::json!("not a number"));
        let error = apply(FIXTURE, &[edit], &document).expect_err("a string is not a port");
        assert!(error.message.contains("want"), "the message names the shape: {error:?}");
        assert_eq!(error.key_path.as_deref(), Some("server.port"));
    }

    /// **A batch naming one key twice is refused whole.** Two edits for one
    /// path have no defined winner, and the second would silently undo the
    /// first while the save still reported a change.
    #[test]
    fn a_batch_naming_one_key_twice_is_refused() {
        let document = document(FIXTURE);
        let first = set_edit(&document, "server.port", serde_json::json!(8791));
        let second = set_edit(&document, "server.port", serde_json::json!(8792));

        let error =
            apply(FIXTURE, &[first, second], &document).expect_err("the duplicate is refused");

        assert!(error.message.contains("server.port"), "{}", error.message);
        assert!(error.message.contains("twice"), "{}", error.message);
        assert_eq!(error.key_path.as_deref(), Some("server.port"));
    }

    /// A project whose org and name carry dots is found by its pattern, not
    /// by splitting the display path on every dot.
    #[test]
    fn a_dotted_project_name_is_located_by_its_pattern() {
        let document = document(FIXTURE);
        let edit = set_edit(
            &document,
            "orgs.Acme.Corp.projects.api.v2.model",
            serde_json::json!("deepseek-v4.1-flash"),
        );
        let out = apply(FIXTURE, &[edit], &document).expect("the dotted project applies");
        assert!(out.contains("[[orgs.projects]]\nname = \"api.v2\""), "{out}");
        assert!(out.contains("model = \"deepseek-v4.1-flash\""), "{out}");
    }

    /// An inline table's entry is rewritten in place.
    #[test]
    fn an_inline_table_entry_is_set() {
        let document = document(FIXTURE);
        let edit = set_edit(
            &document,
            "accounts.One.model_slugs.deepseek-v4.1-flash",
            serde_json::json!("other/flash"),
        );
        let out = apply(FIXTURE, &[edit], &document).expect("the slug applies");
        assert!(out.contains("\"other/flash\""), "the slug moved: {out}");
        assert!(out.contains("display_name = \"One\""), "the account stayed: {out}");
    }

    /// An optional key removed from the file is gone, and its neighbours are
    /// untouched.
    #[test]
    fn a_leaf_removal_takes_only_that_key() {
        let document = document(FIXTURE);
        let (pattern, key_path) = key(&document, "accounts.One.env.FLAG");
        let edit = SettingsEditRequest {
            area: "accounts".to_owned(),
            key_path,
            pattern,
            op: SettingsEditOp::Remove,
            value: None,
        };
        let out = apply(FIXTURE, &[edit], &document).expect("the removal applies");
        assert!(!out.contains("FLAG = \"1\""), "the key went: {out}");
        assert!(out.contains("[accounts.env]"), "the empty table stays: {out}");
    }

    /// A new project is added under its org with the fields the page sent.
    #[test]
    fn a_project_is_added_under_its_org() {
        let document = document(FIXTURE);
        let edit = entry_edit(
            "projects",
            "orgs.Acme.Corp.projects.new-one",
            SettingsEditOp::Add,
            Some(serde_json::json!({
                "name": "new-one",
                "path": "/tmp/new-one",
                "model": "deepseek-v4.1-flash",
            })),
        );
        let out = apply(FIXTURE, &[edit], &document).expect("the project adds");
        assert!(out.contains("name = \"new-one\""), "the project is in the text: {out}");
        assert!(out.contains("path = \"/tmp/new-one\""), "{out}");
    }

    /// An account is removed whole.
    #[test]
    fn an_account_is_removed_whole() {
        let document = document(FIXTURE);
        let edit = entry_edit("accounts", "accounts.Two", SettingsEditOp::Remove, None);
        let out = apply(FIXTURE, &[edit], &document).expect("the account removes");
        assert!(!out.contains("\"Two\""), "the account went: {out}");
        assert!(out.contains("display_name = \"One\""), "the other stayed: {out}");
    }

    /// A model table is added and removed by name.
    #[test]
    fn a_model_table_is_added_and_removed() {
        let document = document(FIXTURE);
        let add = entry_edit(
            "models",
            "models.new-model",
            SettingsEditOp::Add,
            Some(serde_json::json!({ "auto_compact_window": 1024 })),
        );
        let out = apply(FIXTURE, &[add], &document).expect("the model adds");
        assert!(out.contains("[models.new-model]"), "{out}");
        let remove = entry_edit("models", "models.new-model", SettingsEditOp::Remove, None);
        let out = apply(&out, &[remove], &document).expect("the model removes");
        assert!(!out.contains("[models.new-model]"), "{out}");
        assert!(out.contains("[models.\"deepseek-v4.1-flash\"]"), "the other stayed: {out}");
    }

    /// A Slack workspace's pump token changes in place.
    #[test]
    fn a_slack_token_is_set() {
        let document = document(FIXTURE);
        let edit = set_edit(&document, "slack.Work.token", serde_json::json!("xoxp-new"));
        let out = apply(FIXTURE, &[edit], &document).expect("the token applies");
        assert!(out.contains("xoxp-new"), "{out}");
        assert!(out.contains("workspace = \"Work\""), "{out}");
    }

    /// **A removal keeps the comments above the key.** The port carries a
    /// hand-written note; removing the key must move the note, not delete it.
    #[test]
    fn a_key_removal_keeps_its_comments() {
        let document = document(FIXTURE);
        let (pattern, key_path) = key(&document, "server.port");
        let edit = SettingsEditRequest {
            area: "server".to_owned(),
            key_path,
            pattern,
            op: SettingsEditOp::Remove,
            value: None,
        };
        let out = apply(FIXTURE, &[edit], &document).expect("the key removes");
        assert!(!out.contains("port = 8790"), "the key is gone: {out}");
        assert!(out.contains("# the socket's port"), "the note above it stayed: {out}");
    }

    /// **A table's last key takes its comment to the table's end.** Removing
    /// it has no following key to carry the note.
    #[test]
    fn a_last_key_removal_keeps_its_comments() {
        let raw =
            FIXTURE.replace("bind = \"127.0.0.1\"", "# the bind address\nbind = \"127.0.0.1\"");
        let document = document(&raw);
        let (pattern, key_path) = key(&document, "server.bind");
        let edit = SettingsEditRequest {
            area: "server".to_owned(),
            key_path,
            pattern,
            op: SettingsEditOp::Remove,
            value: None,
        };
        let out = apply(&raw, &[edit], &document).expect("the key removes");
        assert!(!out.contains("bind = "), "the key is gone: {out}");
        assert!(out.contains("# the bind address"), "its note stayed: {out}");
    }

    /// **A removal keeps the comments above the entry** it takes.
    #[test]
    fn an_entry_removal_keeps_its_comments() {
        let document = document(FIXTURE);
        let edit = entry_edit("accounts", "accounts.One", SettingsEditOp::Remove, None);
        let out = apply(FIXTURE, &[edit], &document).expect("the account removes");
        assert!(!out.contains("display_name = \"One\""), "the entry is gone: {out}");
        assert!(out.contains("# the first account"), "its note stayed: {out}");
    }

    /// **A CRLF config keeps its line endings.** toml_edit renders `\n`; the
    /// writer must hand back the file's own style.
    #[test]
    fn a_crlf_file_keeps_its_line_endings() {
        let raw = FIXTURE.replace('\n', "\r\n");
        let document = document(&raw);
        let edit = set_edit(&document, "server.port", serde_json::json!(8791));
        let out = apply(&raw, &[edit], &document).expect("the edit applies");
        assert!(out.contains("\r\n"), "still CRLF: {out:?}");
        assert!(!out.replace("\r\n", "").contains('\n'), "no bare LF was introduced: {out:?}");
    }

    /// **A sibling whose name continues the path is not the target.**
    /// Projects `api` and `api.handoff` both match the row for `api`'s own
    /// handoff table, and the row's group names the longer one.
    #[test]
    fn a_sibling_named_like_the_next_segment_is_not_the_target() {
        let raw = r#"
[models."m"]
auto_compact_window = 1

[[accounts]]
display_name = "One"
provider = "anthropic"
token = "t"
models = ["m"]

[[orgs]]
name = "Acme"
accounts = ["One"]

[[orgs.projects]]
name = "api"
path = "/tmp/api"
model = "m"

[orgs.projects.handoff]
enabled = true

[[orgs.projects]]
name = "api.handoff"
path = "/tmp/api.handoff"
model = "m"

[orgs.projects.handoff]
enabled = true
"#;
        let document = document(raw);
        let edit =
            set_edit(&document, "orgs.Acme.projects.api.handoff.enabled", serde_json::json!(false));
        let out = apply(raw, &[edit], &document).expect("the edit applies");
        // **The false is `api`'s**, not merely one of the two: the sibling's
        // table must still read true.
        let mut blocks = out.split("[[orgs.projects]]");
        blocks.next();
        let api_block = blocks.next().unwrap_or_default();
        let sibling_block = blocks.next().unwrap_or_default();
        assert!(api_block.contains("name = \"api\""), "the first block is api: {out}");
        assert!(api_block.contains("enabled = false"), "api's table took the set: {out}");
        assert!(
            sibling_block.contains("name = \"api.handoff\""),
            "the second is the sibling: {out}"
        );
        assert!(sibling_block.contains("enabled = true"), "the sibling kept its value: {out}");
    }

    /// **The last model's comment survives its removal.** An implicit
    /// `[models]` never renders a suffix, so the note moves above the next
    /// root entry.
    #[test]
    fn a_last_model_removal_keeps_its_comments() {
        let raw = r#"
[models."a"]
auto_compact_window = 1

# the bee model
[models."b"]
auto_compact_window = 2

[[accounts]]
display_name = "One"
provider = "anthropic"
token = "t"
models = ["a"]

[[orgs]]
name = "Acme"
accounts = ["One"]

[[orgs.projects]]
name = "api"
path = "/tmp/api"
model = "a"
"#;
        let document = document(raw);
        let edit = entry_edit("models", "models.b", SettingsEditOp::Remove, None);
        let out = apply(raw, &[edit], &document).expect("the model removes");
        assert!(!out.contains("models.\"b\""), "the model went: {out}");
        assert!(out.contains("# the bee model"), "its note stayed: {out}");
    }

    /// **An explicit `[models]` header's comment survives its last model.**
    #[test]
    fn an_explicit_models_header_keeps_its_comment() {
        let raw = r#"
# the models
[models]

[models."a"]
auto_compact_window = 1

[[accounts]]
display_name = "One"
provider = "anthropic"
token = "t"
models = ["a"]

[[orgs]]
name = "Acme"
accounts = ["One"]

[[orgs.projects]]
name = "api"
path = "/tmp/api"
model = "a"
"#;
        let document = document(raw);
        let edit = entry_edit("models", "models.a", SettingsEditOp::Remove, None);
        let out = apply(raw, &[edit], &document).expect("the model removes");
        assert!(!out.contains("models.\"a\""), "the model went: {out}");
        assert!(out.contains("# the models"), "the header's note stayed: {out}");
    }

    /// **An LF file stays LF when a multi-line string carries a CRLF.** The
    /// string's newline is content; the layout is the file's first newline.
    #[test]
    fn an_lf_file_keeps_lf_when_a_string_contains_crlf() {
        let raw = "[server]\nport = 8790\nnote = \"\"\"one\r\ntwo\"\"\"\n";
        let document = document(FIXTURE);
        let edit = set_edit(&document, "server.port", serde_json::json!(8791));
        let out = apply(raw, &[edit], &document).expect("the edit applies");
        assert!(out.contains("one\r\ntwo"), "the string's own CRLF stayed: {out:?}");
        assert!(!out.contains("\r\nport"), "the layout stayed LF: {out:?}");
    }

    /// **A rename and an edit of the same entry share one batch.** The edit
    /// is located by the pre-edit name, so the rename must be applied after
    /// it whatever order the batch arrived in.
    #[test]
    fn a_rename_and_an_edit_of_the_same_entry_apply_together() {
        let document = document(FIXTURE);
        let rename =
            set_edit(&document, "orgs.Acme.Corp.projects.api.v2.name", serde_json::json!("api.v3"));
        let edit =
            set_edit(&document, "orgs.Acme.Corp.projects.api.v2.max_workers", serde_json::json!(4));
        let out = apply(FIXTURE, &[rename, edit], &document).expect("both apply");
        assert!(out.contains("name = \"api.v3\""), "the rename landed: {out}");
        assert!(out.contains("max_workers = 4"), "the edit landed: {out}");
    }

    /// **An add cannot replace an existing entry.** A model table already in
    /// the file is refused rather than silently overwritten.
    #[test]
    fn adding_an_existing_model_is_refused() {
        let document = document(FIXTURE);
        let edit = entry_edit(
            "models",
            "models.deepseek-v4.1-flash",
            SettingsEditOp::Add,
            Some(serde_json::json!({ "auto_compact_window": 1 })),
        );
        let error = apply(FIXTURE, &[edit], &document).expect_err("the add is refused");
        assert!(error.message.contains("already exists"), "{}", error.message);
    }

    /// **A dotted org's project is located by the row's own names.** A path
    /// cut would take the org's inner `.projects.` for the real one and read
    /// the project as the rest of the name.
    #[test]
    fn an_edit_to_a_project_under_a_dotted_org_applies() {
        let raw = FIXTURE.replace("name = \"Acme.Corp\"", "name = \"Acme.projects.Team\"");
        let document = document(&raw);
        let edit = set_edit(
            &document,
            "orgs.Acme.projects.Team.projects.api.v2.permission_mode",
            serde_json::json!("plan"),
        );
        let out = apply(&raw, &[edit], &document).expect("the dotted org's project applies");
        assert!(out.contains("permission_mode = \"plan\""), "{out}");
    }

    /// **A Slack workspace renamed and its token edited share one batch.**
    /// The token edit is keyed by the pre-edit name, so the rename goes last.
    #[test]
    fn a_slack_rename_and_token_edit_apply_together() {
        let document = document(FIXTURE);
        let rename = set_edit(&document, "slack.Work.workspace", serde_json::json!("Home"));
        let token = set_edit(&document, "slack.Work.token", serde_json::json!("xoxp-new"));
        let out = apply(FIXTURE, &[token, rename], &document).expect("both apply");
        assert!(out.contains("workspace = \"Home\""), "{out}");
        assert!(out.contains("xoxp-new"), "{out}");
    }

    /// **A Slack add's identity is the workspace its value names.** A value
    /// naming an existing workspace is refused even under a different path,
    /// or the file holds two entries the pump cannot tell apart.
    #[test]
    fn adding_a_slack_entry_under_an_existing_workspace_is_refused() {
        let document = document(FIXTURE);
        let edit = entry_edit(
            "connectors",
            "slack.Other",
            SettingsEditOp::Add,
            Some(serde_json::json!({ "workspace": "Work", "token": "xoxp-other" })),
        );
        let error = apply(FIXTURE, &[edit], &document).expect_err("the duplicate is refused");
        assert!(error.message.contains("already exists"), "{}", error.message);
    }

    /// **A model's removal keeps the comment above its header.**
    #[test]
    fn a_model_removal_keeps_its_comments() {
        let raw = FIXTURE.replace(
            "[models.\"deepseek-v4.1-flash\"]",
            "# the flash model\n[models.\"deepseek-v4.1-flash\"]",
        );
        let document = document(&raw);
        let edit = entry_edit("models", "models.deepseek-v4.1-flash", SettingsEditOp::Remove, None);
        let out = apply(&raw, &[edit], &document).expect("the model removes");
        assert!(!out.contains("[models."), "the table went: {out}");
        assert!(out.contains("# the flash model"), "its note stayed: {out}");
    }

    /// **An array's only entry takes its comment with it when removed.**
    #[test]
    fn an_only_entry_removal_keeps_its_comments() {
        let raw = FIXTURE.replace("[[slack]]", "# the only workspace\n[[slack]]");
        let document = document(&raw);
        let edit = entry_edit("connectors", "slack.Work", SettingsEditOp::Remove, None);
        let out = apply(&raw, &[edit], &document).expect("the entry removes");
        assert!(!out.contains("[[slack]]"), "the entry went: {out}");
        assert!(out.contains("# the only workspace"), "its note stayed: {out}");
    }

    /// **A CRLF file keeps its endings inside a multi-line string too,**
    /// where the newline is content rather than layout.
    #[test]
    fn a_crlf_multi_line_string_keeps_its_line_endings() {
        let raw = "[server]\r\nport = 8790\r\nnote = \"\"\"one\r\ntwo\"\"\"\r\n";
        let document = document(FIXTURE);
        let edit = set_edit(&document, "server.port", serde_json::json!(8791));
        let out = apply(raw, &[edit], &document).expect("the edit applies");
        assert!(out.contains("one\r\ntwo"), "the string kept its own newline: {out:?}");
        assert!(!out.replace("\r\n", "").contains('\n'), "no bare LF was introduced: {out:?}");
    }

    /// **A project renamed with its org in one batch applies both.** The
    /// project's path is keyed by the org's pre-edit name, so it goes first.
    #[test]
    fn an_org_and_its_project_rename_together() {
        let document = document(FIXTURE);
        let org = set_edit(&document, "orgs.Acme.Corp.name", serde_json::json!("Acme.Labs"));
        let project =
            set_edit(&document, "orgs.Acme.Corp.projects.api.v2.name", serde_json::json!("api.v3"));
        let out = apply(FIXTURE, &[org, project], &document).expect("both renames apply");
        assert!(out.contains("name = \"Acme.Labs\""), "{out}");
        assert!(out.contains("name = \"api.v3\""), "{out}");
    }

    /// **A dotted org is matched from the document's own names.** An org
    /// whose name contains `.projects.` cannot be cut short by a split.
    #[test]
    fn a_project_under_a_dotted_org_is_removed_by_its_own_org() {
        let raw = FIXTURE.replace("name = \"Acme.Corp\"", "name = \"Acme.projects.Team\"");
        let document = document(&raw);
        let edit = entry_edit(
            "projects",
            "orgs.Acme.projects.Team.projects.api.v2",
            SettingsEditOp::Remove,
            None,
        );
        let out = apply(&raw, &[edit], &document).expect("the right project removes");
        assert!(!out.contains("name = \"api.v2\""), "the project is gone: {out}");
        assert!(out.contains("name = \"site\""), "its sibling stayed: {out}");
    }
}