///| Home Repo manifest (`bit-home.toml`).
///
/// A Home Repo is one repository that holds the agent steering files
/// (AGENTS.md, CLAUDE.md, skills, shared docs) and *points at* the other
/// repositories a project spans. The manifest is the machine-readable list
/// of those pointers; `bit home render` turns it into the "Other Repos"
/// section of AGENTS.md, and `bit home sync` / `status` / `wt` act on every
/// listed repository at once, so the set behaves like one virtual repo.
///
/// ```toml
/// [[repo]]
/// name = "storefront"                          # optional, defaults to path basename
/// path = "~/repos/acme/storefront"             # required: where the clone lives
/// url = "git@github.com:acme/storefront.git"   # clone source (needed to clone)
/// description = "Next.js app"
/// branch = "main"                              # optional: branch to clone
/// subdir = "apps/web"                          # optional: sparse checkout of one dir
/// notes = "Read its AGENTS.md before changing it."
/// ```

///|
/// The manifest file name, at the root of the Home Repo.
pub let manifest_file_name : String = "bit-home.toml"

///|
pub suberror HomeError {
  HomeError(String)
} derive(Debug)

///|
pub extend HomeError with Debug::{to_repr}

///|
/// The error text, for display.
pub fn HomeError::message(self : HomeError) -> String {
  match self {
    HomeError(msg) => msg
  }
}

///|
/// One repository the Home Repo points at.
pub(all) struct HomeRepo {
  name : String
  /// Clone location as written in the manifest (`~/` and relative paths
  /// are resolved by `resolve_repo_path`).
  path : String
  url : String?
  description : String?
  branch : String?
  /// Sparse-checkout this directory only (normalized, no leading or
  /// trailing `/`).
  subdir : String?
  notes : String?
} derive(Debug, Eq)

///|
pub extend HomeRepo with Debug::{to_repr}

///|
pub extend HomeRepo with Eq::{not_equal, equal}

///|
pub(all) struct HomeManifest {
  repos : Array[HomeRepo]
} derive(Debug, Eq)

///|
pub extend HomeManifest with Debug::{to_repr}

///|
pub extend HomeManifest with Eq::{not_equal, equal}

///|
let known_repo_keys : Array[String] = [
  "name", "path", "url", "description", "branch", "subdir", "notes",
]

///|
fn home_err(msg : String) -> HomeError {
  HomeError::HomeError(msg)
}

///|
fn toml_string_field(
  table : Map[String, @toml.TomlValue],
  key : String,
  index : Int,
) -> String? raise HomeError {
  match table.get(key) {
    None => None
    Some(@toml.TomlValue::TomlString(v)) => {
      let trimmed = v.trim(chars=" \t").to_owned()
      if trimmed.length() == 0 {
        None
      } else {
        Some(trimmed)
      }
    }
    Some(_) => raise home_err("repo[\{index}]: `\{key}` must be a string")
  }
}

///|
/// Last path component of `path` (ignoring trailing slashes), with a
/// trailing `.git` dropped.
pub fn path_basename(path : String) -> String {
  let mut end = path.length()
  while end > 0 && (path.unsafe_get(end - 1) == '/' || path.unsafe_get(end - 1) == ':') {
    end -= 1
  }
  let mut start = end
  while start > 0 &&
        path.unsafe_get(start - 1) != '/' &&
        path.unsafe_get(start - 1) != ':' {
    start -= 1
  }
  let base = String::unsafe_substring(path, start~, end~)
  if base.has_suffix(".git") && base.length() > 4 {
    String::unsafe_substring(base, start=0, end=base.length() - 4)
  } else {
    base
  }
}

///|
/// Repository names become worktree / display keys: ASCII letters, digits,
/// `.`, `_` and `-`, not `.` or `..`.
pub fn is_valid_repo_name(name : String) -> Bool {
  if name.length() == 0 || name == "." || name == ".." {
    return false
  }
  for c in name {
    if !(
        (c >= 'a' && c <= 'z') ||
        (c >= 'A' && c <= 'Z') ||
        (c >= '0' && c <= '9') ||
        c == '.' ||
        c == '_' ||
        c == '-'
      ) {
      return false
    }
  }
  true
}

///|
/// Normalize a sparse-checkout subdirectory: strip surrounding `/`, reject
/// empty, `.`/`..` components and backslashes.
pub fn normalize_subdir(subdir : String) -> String raise HomeError {
  let parts : Array[String] = []
  for part in subdir.split("/") {
    let p = part.to_owned()
    if p.length() == 0 {
      continue
    }
    if p == "." || p == ".." || p.contains("\\") {
      raise home_err("invalid subdir '\{subdir}'")
    }
    parts.push(p)
  }
  if parts.length() == 0 {
    raise home_err("invalid subdir '\{subdir}'")
  }
  parts.join("/")
}

///|
fn validate_branch(branch : String) -> Unit raise HomeError {
  if branch.has_prefix("-") ||
    branch.contains(" ") ||
    branch.contains("\t") ||
    branch.contains("..") {
    raise home_err("invalid branch '\{branch}'")
  }
}

///|
/// Parse and validate `bit-home.toml`. Unknown keys are rejected so a typo
/// (`subdirs = ...`) is not silently ignored.
pub fn parse_manifest(content : String) -> HomeManifest raise HomeError {
  let root = @toml.parse(content) catch {
    err => raise home_err("\{manifest_file_name}: \{err.to_string()}")
  }
  guard root is @toml.TomlValue::TomlTable(top) else {
    raise home_err("\{manifest_file_name}: expected a table")
  }
  for key, _ in top {
    if key != "repo" {
      raise home_err("\{manifest_file_name}: unknown top-level key `\{key}`")
    }
  }
  let entries : Array[@toml.TomlValue] = match top.get("repo") {
    None => []
    Some(@toml.TomlValue::TomlArray(items)) => items
    Some(_) =>
      raise home_err("\{manifest_file_name}: `repo` must be an array of tables ([[repo]])")
  }
  let repos : Array[HomeRepo] = []
  let seen : Map[String, Bool] = Map([])
  for index, entry in entries {
    guard entry is @toml.TomlValue::TomlTable(table) else {
      raise home_err("repo[\{index}]: expected a table")
    }
    for key, _ in table {
      if !known_repo_keys.contains(key) {
        raise home_err("repo[\{index}]: unknown key `\{key}`")
      }
    }
    guard toml_string_field(table, "path", index) is Some(path) else {
      raise home_err("repo[\{index}]: `path` is required")
    }
    let name = match toml_string_field(table, "name", index) {
      Some(n) => n
      None => path_basename(path)
    }
    if !is_valid_repo_name(name) {
      raise home_err(
        "repo[\{index}]: invalid name '\{name}' (use letters, digits, '.', '_', '-')",
      )
    }
    if seen.contains(name) {
      raise home_err("repo[\{index}]: duplicate name '\{name}'")
    }
    seen[name] = true
    let branch = toml_string_field(table, "branch", index)
    if branch is Some(b) {
      validate_branch(b)
    }
    let subdir = match toml_string_field(table, "subdir", index) {
      Some(s) => Some(normalize_subdir(s))
      None => None
    }
    let url = toml_string_field(table, "url", index)
    if url is Some(u) && u.has_prefix("-") {
      raise home_err("repo[\{index}]: invalid url '\{u}'")
    }
    repos.push({
      name,
      path,
      url,
      description: toml_string_field(table, "description", index),
      branch,
      subdir,
      notes: toml_string_field(table, "notes", index),
    })
  }
  { repos, }
}

///|
pub fn HomeManifest::find(self : HomeManifest, name : String) -> HomeRepo? {
  for repo in self.repos {
    if repo.name == name {
      return Some(repo)
    }
  }
  None
}

///|
/// Absolute location of a repository: `~/x` is under `home`, a relative
/// path is relative to the Home Repo root, an absolute path is kept.
pub fn resolve_repo_path(
  path : String,
  home~ : String,
  home_repo_root~ : String,
) -> String {
  if path == "~" {
    home
  } else if path.has_prefix("~/") {
    home + String::unsafe_substring(path, start=1, end=path.length())
  } else if path.has_prefix("/") {
    path
  } else {
    let rel = if path.has_prefix("./") {
      String::unsafe_substring(path, start=2, end=path.length())
    } else {
      path
    }
    if home_repo_root.has_suffix("/") {
      home_repo_root + rel
    } else {
      home_repo_root + "/" + rel
    }
  }
}

///|
/// Cone-mode sparse-checkout pattern for a normalized subdir.
pub fn sparse_pattern(subdir : String) -> String {
  "/" + subdir + "/"
}

///|
/// Quote a TOML basic string.
pub fn toml_quote(value : String) -> String {
  let sb = StringBuilder()
  sb.write_char('"')
  for c in value {
    match c {
      '"' => sb.write_string("\\\"")
      '\\' => sb.write_string("\\\\")
      '\n' => sb.write_string("\\n")
      '\r' => sb.write_string("\\r")
      '\t' => sb.write_string("\\t")
      _ => sb.write_char(c)
    }
  }
  sb.write_char('"')
  sb.to_string()
}

///|
/// The `[[repo]]` block `bit home add` appends to the manifest. Appending
/// (rather than re-serializing the file) keeps the user's comments.
pub fn repo_toml_block(repo : HomeRepo) -> String {
  let sb = StringBuilder()
  sb.write_string("[[repo]]\n")
  sb.write_string("name = \{toml_quote(repo.name)}\n")
  sb.write_string("path = \{toml_quote(repo.path)}\n")
  let opt = fn(key : String, v : String?) {
    if v is Some(s) {
      sb.write_string("\{key} = \{toml_quote(s)}\n")
    }
  }
  opt("url", repo.url)
  opt("description", repo.description)
  opt("branch", repo.branch)
  opt("subdir", repo.subdir)
  opt("notes", repo.notes)
  sb.to_string()
}

///|
/// Initial manifest written by `bit home init`.
pub let manifest_template : String =
  #|# bit home manifest: the repositories this Home Repo points at.
  #|# `bit home render` turns it into the "Other Repos" section of AGENTS.md;
  #|# `bit home sync` / `bit home status` act on every entry at once.
  #|#
  #|# [[repo]]
  #|# name = "storefront"                          # optional, defaults to the path basename
  #|# path = "~/repos/acme/storefront"             # required: where the clone lives
  #|# url = "git@github.com:acme/storefront.git"   # clone source
  #|# description = "Next.js app"
  #|# branch = "main"                              # optional: branch to clone
  #|# subdir = "apps/web"                          # optional: sparse checkout of one directory
  #|# notes = "Read its AGENTS.md before changing it."
  #|