hanna/fabrica

feat(git): bare-repo creation and the in-process read API

d52473f · hanna committed on 2026-07-25

Begin phase 5. `crates/git` wraps libgit2 (`git2`) for the in-process object
model — transport stays a spawned-`git` concern for later.

- Layout + creation: repo_path shards by ULID (`{root}/{id[0..2]}/{id}.git`);
  create_bare does init_bare with the initial HEAD, the server config
  (logAllRefUpdates, denyNonFastForwards=false, gc.auto=0), and the
  post-receive/pre-receive hooks, cleaning up the directory on any failure.
- Read API in the plain `types` vocabulary (no `git2` in public signatures, so
  `web` never links libgit2 semantics): resolve_ref, tree_entries, blob (with
  binary sniff), branches (ahead/behind vs default), tags (annotated vs
  lightweight), commits (newest-first, optional path filter, paged), commit.
- Oids are hex strings, times epoch-ms; methods are blocking and documented to
  require spawn_blocking off the async runtime.

Integration tests build a real bare repo via git2 and exercise every read.
git2 is pinned to a libgit2-sys matching nixpkgs' libgit2 1.9.4, and the dev
shell exports LD_LIBRARY_PATH for the dynamic link; both are in decisions.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

Cargo.lock +57 −1

Cargo.toml +4 −0

crates/git/Cargo.toml +12 −0

crates/git/src/lib.rs +239 −1

crates/git/src/repo.rs +707 −0

crates/git/src/types.rs +218 −0

docs/decisions.md +30 −0

flake.nix +5 −0

 checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9"
 dependencies = [
  "find-msvc-tools",
  "jobserver",
  "libc",
  "shlex",
+]
@@ @@ -648,6 +650,26 @@ dependencies = [ @@
 [[package]]
 name = "git"
 version = "0.1.0"
 dependencies = [
  "git2",
  "libgit2-sys",
  "model",
  "tempfile",
  "thiserror",
+]
 [[package]]
 name = "git2"
 version = "0.20.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7b88256088d75a56f8ecfa070513a775dd9107f6530ef14919dac831af9cfe2b"
 dependencies = [
  "bitflags",
  "libc",
  "libgit2-sys",
  "log",
  "url",
+]
 [[package]]
 name = "hashbrown"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 [[package]]
 name = "jobserver"
 version = "0.1.35"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1c00acbd29eabad4a2392fa0e921c874934dbbf4194312ad20f04a0ed67a3cb3"
 dependencies = [
  "getrandom 0.4.3",
  "libc",
+]
 [[package]]
 name = "js-sys"
 version = "0.3.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 [[package]]
 name = "libgit2-sys"
 version = "0.18.3+1.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c9b3acc4b91781bb0b3386669d325163746af5f6e4f73e6d2d630e09a35f3487"
 dependencies = [
  "cc",
  "libc",
  "libz-sys",
  "pkg-config",
+]
 [[package]]
 name = "libsqlite3-sys"
 version = "0.37.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ @@ -886,6 +930,18 @@ dependencies = [ @@
+]
 [[package]]
 name = "libz-sys"
 version = "1.1.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "85bc9657773828b90eeb625adff10eeac83cc21bbfd8e23a03eaa8a33c9e28d9"
 dependencies = [
  "cc",
  "libc",
  "pkg-config",
  "vcpkg",
+]
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
  "getrandom 0.4.3",
  "getrandom 0.3.4",
  "once_cell",
  "rustix",
  "windows-sys 0.61.2",

 ulid = "1"
 tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
 tempfile = "3"
 # Git object model (refs, trees, blobs, commits, diffs, signatures). Linked
 # against the system libgit2 (1.9) via pkg-config; the Nix build sets
 # LIBGIT2_NO_VENDOR=1. Client-only for transport — pack transport spawns `git`.
 git2 = { version = "0.20", default-features = false }
 # Authentication primitives. Argon2id password hashing; SHA-256 for session and
 # invite token digests; HMAC-SHA256 for hand-rolled HS256 JWTs (avoiding a `ring`
 # dependency, whose license set is not in our allow-list — see docs/decisions.md);

@@ @@ -10,6 +10,18 @@ repository.workspace = true @@
 publish.workspace = true
 [dependencies]
 model = { workspace = true }
 git2 = { workspace = true }
 thiserror = { workspace = true }
 # Pin the libgit2 bindings to a build that requires libgit2 <= the version
 # nixpkgs ships (1.9.4). git2 0.20's default libgit2-sys (0.18.7, bundling 1.9.6)
 # demands >= 1.9.6 and fails against the system lib under LIBGIT2_NO_VENDOR. This
 # is a direct pin, not used in code — bump it when nixpkgs bumps libgit2. See
 # docs/decisions.md.
 libgit2-sys = "=0.18.3"
 [dev-dependencies]
 tempfile = { workspace = true }
 [lints]
 workspace = true

 lands, this path grows the invite-and-email behaviour; the `passwd` fallback stays
 for SMTP-disabled instances (`mail.backend = "none"`), which is exactly the case
 that motivated it.
 ## 2026-07-24 — git2 pinned to the libgit2 nixpkgs ships (1.9.4)
 **Decision:** `crates/git` depends on `git2` 0.20 with a direct
 `libgit2-sys = "=0.18.3"` pin, and the build uses the **system** libgit2
 (`LIBGIT2_NO_VENDOR=1`, already set in the flake) rather than the vendored copy.
 **Alternatives:** Let `libgit2-sys` build its bundled libgit2 from source (drop
 `LIBGIT2_NO_VENDOR`, add `cmake`); track `git2`'s latest `libgit2-sys`.
 **Rationale:** `git2` 0.20's default `libgit2-sys` (0.18.7, bundling 1.9.6)
 requires libgit2 ≥ 1.9.6 and aborts against nixpkgs' 1.9.4 under
 `LIBGIT2_NO_VENDOR`. `libgit2-sys` 0.18.3 (bundling 1.9.2) requires ≥ 1.9.2,
 which 1.9.4 satisfies. The exact pin makes the coupling explicit and stops a
 stray `cargo update` from reintroducing the mismatch; bump it in lockstep when
 nixpkgs bumps libgit2. Using the system lib keeps builds fast and avoids a `cmake`
 build-dep and a second copy of libgit2 in the graph.
 ## 2026-07-24 — Dev shell sets LD_LIBRARY_PATH for dynamic libgit2
 **Decision:** The `devShells.default` exports
 `LD_LIBRARY_PATH = makeLibraryPath buildInputs`.
 **Alternatives:** Rely on rpath; require developers to set it themselves.
 **Rationale:** Test and bin artifacts built interactively (`cargo test`,
 `cargo run` in the dev shell) link libgit2 dynamically but do not receive the Nix
 build sandbox's rpath, so the loader cannot find `libgit2.so.1.9` and the binary
 exits 127. The Nix build's own checks (`nix flake check`) embed rpath and are
 unaffected; this only fixes the interactive `just check` path.

@@ @@ -158,6 +158,11 @@ @@
             ];
             buildInputs = commonArgs.buildInputs;
             LIBGIT2_NO_VENDOR = "1";
             # Test/bin artifacts built interactively link libgit2 dynamically but
             # do not get the build sandbox's rpath, so the loader needs the lib
             # dirs on the search path for `cargo test`/`cargo run` to work in the
             # shell. (The Nix build embeds rpath itself, so its checks don't.)
             LD_LIBRARY_PATH = pkgs.lib.makeLibraryPath commonArgs.buildInputs;
           };
           formatter = pkgs.nixpkgs-fmt;

@@ @@ -2,4 +2,242 @@ @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 //! The git layer: in-process object reads via libgit2 and spawned pack transport.
 //! The git layer: object-model reads over `git2`, on-disk repository layout, and
 //! (in later phases) attribute resolution, signature verification, and
 //! pack-transport spawning.
 //!
 //! # Division of responsibility
 //!
 //! `git2` (libgit2) is the object-model library — refs, trees, blobs, commits,
 //! revwalks, diffs, signatures. It is **client-only for transport**: there is no
 //! server-side `upload-pack`/`receive-pack`, so clone/fetch/push are handled by
 //! spawning the `git` binary (a later phase). This crate owns the in-process
 //! reads and the bare-repository creation that both paths share.
 //!
 //! # Threading
 //!
 //! libgit2 calls are blocking and `git2::Repository` is not `Sync`. Callers on an
 //! async runtime **MUST** run these methods on `tokio::task::spawn_blocking` (or a
 //! bounded blocking pool); [`Repo`] is opened per operation, which is acceptable
 //! for the MVP. Nothing here spawns threads or touches the network.
 //!
 //! # Layout
 //!
 //! Repositories live at `{repo_dir}/{id[0..2]}/{id}.git` keyed by ULID, never by
 //! name, so renames and group moves are metadata-only. The database is the sole
 //! name→path authority; [`repo_path`] is the one place that mapping is computed.
 mod repo;
 mod types;
 use std::fs;
 use std::io;
 use std::os::unix::fs::PermissionsExt;
 use std::path::{Path, PathBuf};
 use git2::{Repository, RepositoryInitOptions};
 pub use crate::repo::Repo;
 pub use crate::types::{
     Blob, BranchInfo, CommitDetail, CommitSummary, EntryKind, Oid, Page, Person, RefKind, Resolved,
     TagInfo, TreeEntry,
 };
 /// An error from the git layer.
 #[derive(Debug, thiserror::Error)]
 pub enum GitError {
     /// An error surfaced by libgit2.
     #[error(transparent)]
     Libgit2(#[from] git2::Error),
     /// A filesystem operation failed, with the path that was being touched.
     #[error("git io error at {path}: {source}")]
     Io {
         /// The path involved.
         path: PathBuf,
         /// The underlying I/O error.
         source: io::Error,
     },
     /// A repository id was too short to shard (ids are 26-char ULIDs).
     #[error("repository id {0:?} is too short")]
     BadId(String),
     /// A revision string did not resolve to any ref or object.
     #[error("revision {0:?} not found")]
     RevNotFound(String),
     /// A path was not present in the given tree.
     #[error("path {0:?} not found")]
     PathNotFound(String),
     /// A path resolved to something other than a file where a file was required.
     #[error("path {0:?} is not a file")]
     NotAFile(String),
+}
 /// Compute the on-disk path of a repository from its id: `{root}/{id[0..2]}/{id}.git`.
 ///
 /// # Errors
 ///
 /// Returns [`GitError::BadId`] if `id` is shorter than the two-character shard
 /// prefix.
 pub fn repo_path(root: &Path, id: &str) -> Result<PathBuf, GitError> {
     if id.len() < 2 {
         return Err(GitError::BadId(id.to_string()));
+    }
     Ok(root.join(&id[0..2]).join(format!("{id}.git")))
+}
 /// Create a bare repository for `id` under `root` and return an open handle.
 ///
 /// Performs the filesystem half of repo creation (the caller inserts the database
 /// row): `init_bare` with `HEAD` pointing at `default_branch`; the config the
 /// server relies on (`core.logAllRefUpdates=true`, `receive.denyNonFastForwards=
 /// false`, `gc.auto=0` — maintenance is fabrica-driven, not push-driven); and the
 /// `post-receive`/`pre-receive` hooks that shell out to `hook_binary`.
 ///
 /// On any failure after the directory is created, the partially built directory
 /// is removed so a retry starts clean.
 ///
 /// # Errors
 ///
 /// Returns [`GitError`] if the id is invalid, the directory already exists, or any
 /// libgit2/filesystem step fails.
 pub fn create_bare(
     root: &Path,
     id: &str,
     default_branch: &str,
     hook_binary: &Path,
 ) -> Result<Repo, GitError> {
     let path = repo_path(root, id)?;
     if path.exists() {
         return Err(GitError::Io {
             path: path.clone(),
             source: io::Error::new(io::ErrorKind::AlreadyExists, "repository directory exists"),
         });
+    }
     if let Some(parent) = path.parent() {
         fs::create_dir_all(parent).map_err(|source| GitError::Io {
             path: parent.to_path_buf(),
             source,
         })?;
+    }
     // Any error past this point should not leave a half-built repo behind.
     match init_inner(&path, default_branch, hook_binary) {
         Ok(()) => Repo::open_path(&path),
         Err(err) => {
             let _ = fs::remove_dir_all(&path);
             Err(err)
+        }
+    }
+}
 /// The fallible body of [`create_bare`], separated so the caller can clean up on
 /// any error.
 fn init_inner(path: &Path, default_branch: &str, hook_binary: &Path) -> Result<(), GitError> {
     let mut opts = RepositoryInitOptions::new();
     opts.bare(true).initial_head(default_branch).mkpath(true);
     let repo = Repository::init_opts(path, &opts)?;
     let mut config = repo.config()?;
     config.set_bool("core.logallrefupdates", true)?;
     config.set_bool("receive.denyNonFastForwards", false)?;
     config.set_i32("gc.auto", 0)?;
     install_hooks(path, hook_binary)?;
     Ok(())
+}
 /// Write the `post-receive` and `pre-receive` hooks. `post-receive` dispatches to
 /// `fabrica hook post-receive`; `pre-receive` is a reserved no-op. Both are made
 /// executable.
 fn install_hooks(repo_path: &Path, hook_binary: &Path) -> Result<(), GitError> {
     let hooks_dir = repo_path.join("hooks");
     fs::create_dir_all(&hooks_dir).map_err(|source| GitError::Io {
         path: hooks_dir.clone(),
         source,
     })?;
     let binary = hook_binary.display();
     write_hook(
         &hooks_dir.join("post-receive"),
         &format!("#!/bin/sh\nexec \"{binary}\" hook post-receive\n"),
     )?;
     // Reserved for future branch protection; accepts every push for now.
     write_hook(&hooks_dir.join("pre-receive"), "#!/bin/sh\nexit 0\n")?;
     Ok(())
+}
 /// Write a single hook file and mark it executable (`0o755`).
 fn write_hook(path: &Path, contents: &str) -> Result<(), GitError> {
     fs::write(path, contents).map_err(|source| GitError::Io {
         path: path.to_path_buf(),
         source,
     })?;
     fs::set_permissions(path, fs::Permissions::from_mode(0o755)).map_err(|source| {
         GitError::Io {
             path: path.to_path_buf(),
             source,
+        }
     })?;
     Ok(())
+}
 #[cfg(test)]
 mod tests {
     #![allow(clippy::unwrap_used)]
     use super::*;
     #[test]
     fn repo_path_shards_by_id_prefix() {
         let root = Path::new("/srv/repos");
         let path = repo_path(root, "01hzxk9m2n8p7q6r5s4t3v2w1x").unwrap();
         assert_eq!(
             path,
             Path::new("/srv/repos/01/01hzxk9m2n8p7q6r5s4t3v2w1x.git")
         );
+    }
     #[test]
     fn repo_path_rejects_short_ids() {
         assert!(matches!(
             repo_path(Path::new("/srv"), "a"),
             Err(GitError::BadId(_))
         ));
+    }
     #[test]
     fn create_bare_sets_head_config_and_hooks() {
         let dir = tempfile::tempdir().unwrap();
         let repo = create_bare(
             dir.path(),
             "01hzxk9m2n8p7q6r5s4t3v2w1x",
             "trunk",
             Path::new("/usr/bin/fabrica"),
+        )
         .unwrap();
         // HEAD points at the requested initial branch.
         assert_eq!(repo.head_branch().unwrap().as_deref(), Some("trunk"));
         let path = repo_path(dir.path(), "01hzxk9m2n8p7q6r5s4t3v2w1x").unwrap();
         // The hook exists, is executable, and dispatches to `fabrica hook`.
         let hook = path.join("hooks").join("post-receive");
         let body = std::fs::read_to_string(&hook).unwrap();
         assert!(body.contains("hook post-receive"), "body: {body}");
         let mode = std::fs::metadata(&hook).unwrap().permissions().mode();
         assert_eq!(mode & 0o111, 0o111, "hook must be executable");
+    }
     #[test]
     fn create_bare_is_not_clobbering() {
         let dir = tempfile::tempdir().unwrap();
         let id = "01hzxk9m2n8p7q6r5s4t3v2w1x";
         create_bare(dir.path(), id, "main", Path::new("/usr/bin/fabrica")).unwrap();
         // A second create at the same id fails (the directory already exists).
         assert!(create_bare(dir.path(), id, "main", Path::new("/usr/bin/fabrica")).is_err());
+    }
+}

@@ @@ -0,0 +1,707 @@ @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 //! An open repository and its read operations.
 //!
 //! Every method here is synchronous and blocking; see the crate docs for the
 //! `spawn_blocking` requirement. The public surface speaks only in the plain
 //! [`crate::types`] vocabulary — `git2` handles never escape this module.
 use std::path::Path;
 use git2::{BranchType, Commit, Repository, Signature, Sort, TreeEntry as GitTreeEntry};
 use crate::GitError;
 use crate::types::{
     Blob, BranchInfo, CommitDetail, CommitSummary, EntryKind, Oid, Page, Person, RefKind, Resolved,
     TagInfo, TreeEntry,
 };
 /// Filemode bits git uses to distinguish tree-entry kinds.
 const MODE_DIR: i32 = 0o040_000;
 const MODE_SYMLINK: i32 = 0o120_000;
 const MODE_SUBMODULE: i32 = 0o160_000;
 /// Bytes sniffed from the head of a blob when deciding whether it is binary.
 const BINARY_SNIFF_BYTES: usize = 8_000;
 /// An open bare repository.
 pub struct Repo {
     inner: Repository,
+}
 impl Repo {
     /// Open the repository at `path` (expected to be a bare `.git` directory).
     ///
     /// # Errors
     ///
     /// Returns [`GitError::Libgit2`] if the path is not a repository.
     pub fn open_path(path: &Path) -> Result<Self, GitError> {
         Ok(Self {
             inner: Repository::open_bare(path)?,
         })
+    }
     /// The branch name `HEAD` points at, even when that branch is unborn (a
     /// freshly created repo with no commits). Returns `None` if `HEAD` is
     /// detached.
     ///
     /// # Errors
     ///
     /// Returns [`GitError::Libgit2`] if `HEAD` cannot be read.
     pub fn head_branch(&self) -> Result<Option<String>, GitError> {
         let head = self.inner.find_reference("HEAD")?;
         Ok(head
             .symbolic_target()
             .and_then(|t| t.strip_prefix("refs/heads/"))
             .map(str::to_string))
+    }
     /// Resolve a revision string — a branch or tag name, `HEAD`, or a raw commit
     /// id — to the commit it names.
     ///
     /// Resolution order is branch, then tag, then a general parse (which covers
     /// `HEAD`, full and abbreviated oids, and revspecs). A branch and a tag of the
     /// same name resolve to the branch, matching git's own precedence for a bare
     /// short name in this context.
     ///
     /// # Errors
     ///
     /// Returns [`GitError::RevNotFound`] if nothing matches.
     pub fn resolve_ref(&self, rev: &str) -> Result<Resolved, GitError> {
         if let Ok(branch) = self.inner.find_branch(rev, BranchType::Local) {
             let commit = branch.get().peel_to_commit()?;
             return Ok(Resolved {
                 oid: oid_of(commit.id()),
                 kind: RefKind::Branch,
                 name: rev.to_string(),
             });
+        }
         if let Ok(reference) = self.inner.find_reference(&format!("refs/tags/{rev}")) {
             let commit = reference.peel_to_commit()?;
             return Ok(Resolved {
                 oid: oid_of(commit.id()),
                 kind: RefKind::Tag,
                 name: rev.to_string(),
             });
+        }
         let object = self
             .inner
             .revparse_single(rev)
             .map_err(|_| GitError::RevNotFound(rev.to_string()))?;
         let commit = object
             .peel_to_commit()
             .map_err(|_| GitError::RevNotFound(rev.to_string()))?;
         Ok(Resolved {
             oid: oid_of(commit.id()),
             kind: if rev == "HEAD" {
                 RefKind::Head
             } else {
                 RefKind::Commit
             },
             name: rev.to_string(),
         })
+    }
     /// List the entries of the tree at `path` within revision `rev`. An empty
     /// `path` lists the root tree. Directories sort before files, each
     /// alphabetically.
     ///
     /// # Errors
     ///
     /// Returns [`GitError::PathNotFound`] if `path` is absent or names a file.
     pub fn tree_entries(&self, rev: &Resolved, path: &Path) -> Result<Vec<TreeEntry>, GitError> {
         let commit = self.commit_at(&rev.oid)?;
         let root = commit.tree()?;
         let tree = if path.components().next().is_none() {
             root
         } else {
             let entry = root
                 .get_path(path)
                 .map_err(|_| GitError::PathNotFound(path.display().to_string()))?;
             entry
                 .to_object(&self.inner)?
                 .into_tree()
                 .map_err(|_| GitError::PathNotFound(path.display().to_string()))?
         };
         let mut entries: Vec<TreeEntry> = tree
             .iter()
             .map(|entry| self.map_tree_entry(&entry))
             .collect();
         entries.sort_by(|a, b| {
             let a_dir = a.kind == EntryKind::Directory;
             let b_dir = b.kind == EntryKind::Directory;
             b_dir.cmp(&a_dir).then_with(|| a.name.cmp(&b.name))
         });
         Ok(entries)
+    }
     /// Read the file at `path` within revision `rev`.
     ///
     /// # Errors
     ///
     /// Returns [`GitError::PathNotFound`] if `path` is absent, or
     /// [`GitError::NotAFile`] if it names a directory or submodule.
     pub fn blob(&self, rev: &Resolved, path: &Path) -> Result<Blob, GitError> {
         let commit = self.commit_at(&rev.oid)?;
         let entry = commit
             .tree()?
             .get_path(path)
             .map_err(|_| GitError::PathNotFound(path.display().to_string()))?;
         let object = entry.to_object(&self.inner)?;
         let blob = object
             .into_blob()
             .map_err(|_| GitError::NotAFile(path.display().to_string()))?;
         let content = blob.content().to_vec();
         let size = content.len() as u64;
         Ok(Blob {
             is_binary: looks_binary(&content),
             size,
             content,
         })
+    }
     /// The local branches, each with its position (ahead/behind) relative to the
     /// default branch and its tip commit.
     ///
     /// # Errors
     ///
     /// Returns [`GitError::Libgit2`] on a libgit2 failure.
     pub fn branches(&self) -> Result<Vec<BranchInfo>, GitError> {
         let default = self.head_branch()?;
         let default_oid = default
             .as_deref()
             .and_then(|name| self.inner.find_branch(name, BranchType::Local).ok())
             .and_then(|branch| branch.get().peel_to_commit().ok())
             .map(|commit| commit.id());
         let mut out = Vec::new();
         for branch in self.inner.branches(Some(BranchType::Local))? {
             let (branch, _) = branch?;
             let Some(name) = branch.name()?.map(str::to_string) else {
                 continue;
             };
             let tip = branch.get().peel_to_commit()?;
             let (ahead, behind) = match default_oid {
                 Some(base) if base != tip.id() => self.inner.graph_ahead_behind(tip.id(), base)?,
                 _ => (0, 0),
             };
             out.push(BranchInfo {
                 is_default: default.as_deref() == Some(name.as_str()),
                 name,
                 oid: oid_of(tip.id()),
                 ahead,
                 behind,
                 tip: commit_summary(&tip),
             });
+        }
         out.sort_by(|a, b| {
             b.is_default
                 .cmp(&a.is_default)
                 .then_with(|| a.name.cmp(&b.name))
         });
         Ok(out)
+    }
     /// The tags, peeled to the commit each ultimately points at, annotated tags
     /// carrying their message and tagger.
     ///
     /// # Errors
     ///
     /// Returns [`GitError::Libgit2`] on a libgit2 failure.
     pub fn tags(&self) -> Result<Vec<TagInfo>, GitError> {
         let mut out = Vec::new();
         for name in self.inner.tag_names(None)?.iter().flatten() {
             let object = self.inner.revparse_single(&format!("refs/tags/{name}"))?;
             let commit = object.peel_to_commit()?;
             let (annotated, message, tagger) = match object.as_tag() {
                 Some(tag) => (
                     true,
                     tag.message().map(str::to_string),
                     tag.tagger().as_ref().map(person),
                 ),
                 None => (false, None, None),
             };
             out.push(TagInfo {
                 name: name.to_string(),
                 oid: oid_of(commit.id()),
                 annotated,
                 message,
                 tagger,
             });
+        }
         out.sort_by(|a, b| a.name.cmp(&b.name));
         Ok(out)
+    }
     /// Walk commits reachable from `rev`, newest first, returning one page.
     ///
     /// When `path` is given, only commits that changed that path are returned
     /// (compared against the first parent — a pragmatic history simplification,
     /// not full merge-aware path following). Paging is applied *after* filtering.
     ///
     /// # Errors
     ///
     /// Returns [`GitError::Libgit2`] on a libgit2 failure.
     pub fn commits(
         &self,
         rev: &Resolved,
         path: Option<&Path>,
         page: Page,
     ) -> Result<Vec<CommitSummary>, GitError> {
         let start = git2::Oid::from_str(rev.oid.as_str())?;
         let mut walk = self.inner.revwalk()?;
         walk.set_sorting(Sort::TIME)?;
         walk.push(start)?;
         let mut out = Vec::with_capacity(page.limit);
         let mut skipped = 0usize;
         for oid in walk {
             let commit = self.inner.find_commit(oid?)?;
             if let Some(path) = path {
                 if !commit_touches(&commit, path)? {
                     continue;
+                }
+            }
             if skipped < page.offset {
                 skipped += 1;
                 continue;
+            }
             out.push(commit_summary(&commit));
             if out.len() >= page.limit {
                 break;
+            }
+        }
         Ok(out)
+    }
     /// Fetch a single commit in full.
     ///
     /// # Errors
     ///
     /// Returns [`GitError::RevNotFound`] if no such commit exists.
     pub fn commit(&self, oid: &Oid) -> Result<CommitDetail, GitError> {
         let commit = self.commit_at(oid)?;
         Ok(CommitDetail {
             oid: oid_of(commit.id()),
             message: commit.message().unwrap_or("").to_string(),
             author: person(&commit.author()),
             committer: person(&commit.committer()),
             parents: commit.parent_ids().map(oid_of).collect(),
             tree: oid_of(commit.tree_id()),
         })
+    }
     /// Look up a commit by our [`Oid`], mapping a miss to [`GitError::RevNotFound`].
     fn commit_at(&self, oid: &Oid) -> Result<Commit<'_>, GitError> {
         let parsed = git2::Oid::from_str(oid.as_str())
             .map_err(|_| GitError::RevNotFound(oid.to_string()))?;
         self.inner
             .find_commit(parsed)
             .map_err(|_| GitError::RevNotFound(oid.to_string()))
+    }
     /// Map a libgit2 tree entry into our [`TreeEntry`], reading blob sizes for
     /// files and symlinks.
     fn map_tree_entry(&self, entry: &GitTreeEntry<'_>) -> TreeEntry {
         let mode = entry.filemode();
         let kind = match mode {
             MODE_DIR => EntryKind::Directory,
             MODE_SUBMODULE => EntryKind::Submodule,
             MODE_SYMLINK => EntryKind::Symlink,
             _ => EntryKind::File,
         };
         let size = match kind {
             EntryKind::File | EntryKind::Symlink => self
                 .inner
                 .find_blob(entry.id())
                 .ok()
                 .map(|b| b.size() as u64),
             EntryKind::Directory | EntryKind::Submodule => None,
         };
         TreeEntry {
             name: entry.name().unwrap_or_default().to_string(),
             kind,
             // Filemodes are small positive octal constants; the fallback is
             // unreachable for a well-formed tree entry.
             mode: u32::try_from(mode).unwrap_or(0),
             oid: oid_of(entry.id()),
             size,
+        }
+    }
+}
 /// Whether `commit` changed `path` relative to its first parent (or, for a root
 /// commit, whether the path exists in it).
 fn commit_touches(commit: &Commit<'_>, path: &Path) -> Result<bool, GitError> {
     let here = entry_oid(commit, path)?;
     match commit.parent(0) {
         Ok(parent) => Ok(here != entry_oid(&parent, path)?),
         // No parent: the commit touches the path iff the path exists in it.
         Err(_) => Ok(here.is_some()),
+    }
+}
 /// The object id at `path` in a commit's tree, or `None` if the path is absent.
 fn entry_oid(commit: &Commit<'_>, path: &Path) -> Result<Option<git2::Oid>, GitError> {
     let tree = commit.tree()?;
     Ok(tree.get_path(path).ok().map(|entry| entry.id()))
+}
 /// Convert a libgit2 oid to our hex [`Oid`].
 fn oid_of(oid: git2::Oid) -> Oid {
     Oid::new(oid.to_string())
+}
 /// Build a [`Person`] from a libgit2 signature, converting the second-resolution
 /// time to epoch milliseconds.
 fn person(sig: &Signature<'_>) -> Person {
     Person {
         name: sig.name().unwrap_or_default().to_string(),
         email: sig.email().unwrap_or_default().to_string(),
         time_ms: sig.when().seconds().saturating_mul(1000),
+    }
+}
 /// Build a [`CommitSummary`] for a log row.
 fn commit_summary(commit: &Commit<'_>) -> CommitSummary {
     CommitSummary {
         oid: oid_of(commit.id()),
         summary: commit.summary().unwrap_or("").to_string(),
         author: person(&commit.author()),
         parents: commit.parent_count(),
+    }
+}
 /// Heuristic binary sniff: a NUL byte in the head of the content marks it binary,
 /// matching git's own `core.check-blob-content` behaviour closely enough for a
 /// "don't try to render this" decision.
 fn looks_binary(bytes: &[u8]) -> bool {
     let window = &bytes[..bytes.len().min(BINARY_SNIFF_BYTES)];
     window.contains(&0)
+}
 #[cfg(test)]
 mod tests {
     #![allow(clippy::unwrap_used, clippy::expect_used)]
     use std::path::{Path, PathBuf};
     use git2::{Repository, Signature, Time};
     use tempfile::TempDir;
     use super::*;
     use crate::{create_bare, repo_path};
     const ID: &str = "01hzxk9m2n8p7q6r5s4t3v2w1x";
     /// A populated bare repository plus the temp dir keeping it alive.
     struct Fixture {
         _dir: TempDir,
         path: PathBuf,
         /// Oids of the commits made, in creation order.
         commits: Vec<git2::Oid>,
+    }
     /// Build a bare repo with:
     /// - `main`: commit1 (README + src/main.rs), commit2 (README changed only);
     /// - `feature`: commit3 on top of commit2 (adds src/extra.rs);
     /// - an annotated tag `v1.0` on commit1 and a lightweight tag `light` on commit2.
     fn fixture() -> Fixture {
         let dir = tempfile::tempdir().unwrap();
         create_bare(dir.path(), ID, "main", Path::new("/usr/bin/fabrica")).unwrap();
         let path = repo_path(dir.path(), ID).unwrap();
         let raw = Repository::open_bare(&path).unwrap();
         let c1 = commit(
             &raw,
             "main",
             &[],
             &[("README.md", "hello\n"), ("src/main.rs", "fn main() {}\n")],
             "initial import",
 ,
         );
         let c2 = commit(
             &raw,
             "main",
             &[c1],
             &[
                 ("README.md", "hello world\n"),
                 ("src/main.rs", "fn main() {}\n"),
             ],
             "expand readme",
 ,
         );
         let c3 = commit(
             &raw,
             "feature",
             &[c2],
             &[
                 ("README.md", "hello world\n"),
                 ("src/main.rs", "fn main() {}\n"),
                 ("src/extra.rs", "// extra\n"),
             ],
             "add extra module",
 ,
         );
         // Tags: annotated on c1, lightweight on c2.
         let obj = raw.find_object(c1, None).unwrap();
         let tagger = Signature::new("Ada", "ada@example.com", &Time::new(10_000, 0)).unwrap();
         raw.tag("v1.0", &obj, &tagger, "the first release", false)
             .unwrap();
         raw.reference("refs/tags/light", c2, true, "lightweight")
             .unwrap();
         Fixture {
             _dir: dir,
             path,
             commits: vec![c1, c2, c3],
+        }
+    }
     /// Write `files` (paths may contain one level of nesting) as a tree and commit
     /// it onto `branch`, returning the new commit oid. `t` seeds the commit time so
     /// ordering is deterministic.
     fn commit(
         raw: &Repository,
         branch: &str,
         parents: &[git2::Oid],
         files: &[(&str, &str)],
         message: &str,
         t: i64,
     ) -> git2::Oid {
         use std::collections::BTreeMap;
         // Group files by their (single) directory prefix.
         let mut by_dir: BTreeMap<Option<String>, Vec<(String, git2::Oid)>> = BTreeMap::new();
         for (path, content) in files {
             let blob = raw.blob(content.as_bytes()).unwrap();
             let (dir, name) = match path.split_once('/') {
                 Some((dir, name)) => (Some(dir.to_string()), name.to_string()),
                 None => (None, (*path).to_string()),
             };
             by_dir.entry(dir).or_default().push((name, blob));
+        }
         let mut root = raw.treebuilder(None).unwrap();
         for (dir, entries) in by_dir {
             match dir {
                 None => {
                     for (name, blob) in entries {
                         root.insert(&name, blob, 0o100_644).unwrap();
+                    }
+                }
                 Some(dir) => {
                     let mut sub = raw.treebuilder(None).unwrap();
                     for (name, blob) in entries {
                         sub.insert(&name, blob, 0o100_644).unwrap();
+                    }
                     let sub_oid = sub.write().unwrap();
                     root.insert(&dir, sub_oid, 0o040_000).unwrap();
+                }
+            }
+        }
         let tree_oid = root.write().unwrap();
         let tree = raw.find_tree(tree_oid).unwrap();
         let sig = Signature::new("Ada Lovelace", "ada@example.com", &Time::new(t, 0)).unwrap();
         let parent_commits: Vec<_> = parents
             .iter()
             .map(|p| raw.find_commit(*p).unwrap())
             .collect();
         let parent_refs: Vec<&git2::Commit> = parent_commits.iter().collect();
         raw.commit(
             Some(&format!("refs/heads/{branch}")),
             &sig,
             &sig,
             message,
             &tree,
             &parent_refs,
+        )
         .unwrap()
+    }
     fn open(fx: &Fixture) -> Repo {
         Repo::open_path(&fx.path).unwrap()
+    }
     #[test]
     fn resolve_ref_covers_branch_tag_head_oid_and_miss() {
         let fx = fixture();
         let repo = open(&fx);
         let c2 = fx.commits[1].to_string();
         let main = repo.resolve_ref("main").unwrap();
         assert_eq!(main.kind, RefKind::Branch);
         assert_eq!(main.oid.as_str(), c2);
         let head = repo.resolve_ref("HEAD").unwrap();
         assert_eq!(head.kind, RefKind::Head);
         assert_eq!(head.oid.as_str(), c2, "HEAD tracks the default branch");
         let tag = repo.resolve_ref("v1.0").unwrap();
         assert_eq!(tag.kind, RefKind::Tag);
         assert_eq!(tag.oid.as_str(), fx.commits[0].to_string());
         let raw = repo.resolve_ref(&c2).unwrap();
         assert_eq!(raw.kind, RefKind::Commit);
         assert_eq!(raw.oid.as_str(), c2);
         assert!(matches!(
             repo.resolve_ref("nope"),
             Err(GitError::RevNotFound(_))
         ));
+    }
     #[test]
     fn tree_entries_lists_root_and_subdir_dirs_first() {
         let fx = fixture();
         let repo = open(&fx);
         let main = repo.resolve_ref("main").unwrap();
         let root = repo.tree_entries(&main, Path::new("")).unwrap();
         let names: Vec<_> = root.iter().map(|e| e.name.as_str()).collect();
         assert_eq!(names, ["src", "README.md"], "directories sort first");
         assert_eq!(root[0].kind, EntryKind::Directory);
         assert_eq!(root[1].kind, EntryKind::File);
         assert_eq!(root[1].size, Some("hello world\n".len() as u64));
         let src = repo.tree_entries(&main, Path::new("src")).unwrap();
         assert_eq!(
             src.iter().map(|e| e.name.as_str()).collect::<Vec<_>>(),
             ["main.rs"]
         );
         assert!(matches!(
             repo.tree_entries(&main, Path::new("does/not/exist")),
             Err(GitError::PathNotFound(_))
         ));
         // A file path is not a directory.
         assert!(matches!(
             repo.tree_entries(&main, Path::new("README.md")),
             Err(GitError::PathNotFound(_))
         ));
+    }
     #[test]
     fn blob_reads_content_and_flags() {
         let fx = fixture();
         let repo = open(&fx);
         let main = repo.resolve_ref("main").unwrap();
         let readme = repo.blob(&main, Path::new("README.md")).unwrap();
         assert_eq!(readme.content, b"hello world\n");
         assert_eq!(readme.size, 12);
         assert!(!readme.is_binary);
         // A directory is not a file.
         assert!(matches!(
             repo.blob(&main, Path::new("src")),
             Err(GitError::NotAFile(_))
         ));
         assert!(matches!(
             repo.blob(&main, Path::new("missing")),
             Err(GitError::PathNotFound(_))
         ));
+    }
     #[test]
     fn branches_report_default_and_ahead_behind() {
         let fx = fixture();
         let repo = open(&fx);
         let branches = repo.branches().unwrap();
         let names: Vec<_> = branches.iter().map(|b| b.name.as_str()).collect();
         assert_eq!(names, ["main", "feature"], "default sorts first");
         let main = &branches[0];
         assert!(main.is_default);
         assert_eq!((main.ahead, main.behind), (0, 0));
         let feature = &branches[1];
         assert!(!feature.is_default);
         // feature is one commit ahead of main and behind by none.
         assert_eq!((feature.ahead, feature.behind), (1, 0));
         assert_eq!(feature.tip.summary, "add extra module");
+    }
     #[test]
     fn tags_distinguish_annotated_from_lightweight() {
         let fx = fixture();
         let repo = open(&fx);
         let tags = repo.tags().unwrap();
         let names: Vec<_> = tags.iter().map(|t| t.name.as_str()).collect();
         assert_eq!(names, ["light", "v1.0"]);
         let light = tags.iter().find(|t| t.name == "light").unwrap();
         assert!(!light.annotated);
         assert_eq!(light.oid.as_str(), fx.commits[1].to_string());
         assert!(light.message.is_none());
         let v1 = tags.iter().find(|t| t.name == "v1.0").unwrap();
         assert!(v1.annotated);
         assert_eq!(v1.oid.as_str(), fx.commits[0].to_string());
         assert_eq!(v1.message.as_deref(), Some("the first release"));
         assert_eq!(v1.tagger.as_ref().unwrap().name, "Ada");
+    }
     #[test]
     fn commits_walk_newest_first_and_filter_by_path() {
         let fx = fixture();
         let repo = open(&fx);
         let main = repo.resolve_ref("main").unwrap();
         let all = repo.commits(&main, None, Page::first(10)).unwrap();
         let summaries: Vec<_> = all.iter().map(|c| c.summary.as_str()).collect();
         assert_eq!(summaries, ["expand readme", "initial import"]);
         // Paging: skip the newest, take one.
         let page = repo
             .commits(
                 &main,
                 None,
                 Page {
                     offset: 1,
                     limit: 1,
                 },
+            )
             .unwrap();
         assert_eq!(page.len(), 1);
         assert_eq!(page[0].summary, "initial import");
         // src/main.rs was only introduced in commit1 and unchanged since.
         let touched = repo
             .commits(&main, Some(Path::new("src/main.rs")), Page::first(10))
             .unwrap();
         assert_eq!(
             touched
                 .iter()
                 .map(|c| c.summary.as_str())
                 .collect::<Vec<_>>(),
             ["initial import"]
         );
+    }
     #[test]
     fn commit_returns_full_detail() {
         let fx = fixture();
         let repo = open(&fx);
         let c2 = Oid::new(fx.commits[1].to_string());
         let detail = repo.commit(&c2).unwrap();
         assert_eq!(detail.message, "expand readme");
         assert_eq!(detail.author.name, "Ada Lovelace");
         assert_eq!(detail.author.email, "ada@example.com");
         assert_eq!(detail.parents, vec![Oid::new(fx.commits[0].to_string())]);
         assert!(matches!(
             repo.commit(&Oid::new("0".repeat(40))),
             Err(GitError::RevNotFound(_))
         ));
+    }
+}

@@ @@ -0,0 +1,218 @@ @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 //! The public vocabulary of the git layer.
 //!
 //! None of these types expose `git2`: the object ids are plain hex strings, times
 //! are epoch-millisecond integers, and the shapes carry exactly what the `web`
 //! and `api` crates render — so those crates never link against libgit2 semantics
 //! and the read API stays swappable.
 /// A git object id, stored as its lowercase 40-char hex string.
 ///
 /// A newtype rather than a bare `String` so it cannot be confused with a ref
 /// name or a path, and so the `git2` conversion stays inside this crate.
 #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct Oid(String);
 impl Oid {
     /// Wrap a hex string as an [`Oid`]. The value is lowercased; no validation is
     /// performed here — resolution against a repository is where an unknown id is
     /// rejected.
     #[must_use]
     pub fn new(hex: impl Into<String>) -> Self {
         Self(hex.into().to_lowercase())
+    }
     /// The hex string.
     #[must_use]
     pub fn as_str(&self) -> &str {
         &self.0
+    }
     /// The conventional 7-character short form for display.
     #[must_use]
     pub fn short(&self) -> &str {
         let end = self.0.len().min(7);
         &self.0[..end]
+    }
+}
 impl std::fmt::Display for Oid {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.write_str(&self.0)
+    }
+}
 /// What a ref string resolved to.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum RefKind {
     /// A branch (`refs/heads/…`).
     Branch,
     /// A tag (`refs/tags/…`), annotated or lightweight.
     Tag,
     /// A raw commit id, given directly rather than through a ref.
     Commit,
     /// The repository `HEAD`.
     Head,
+}
 /// A resolved revision: the commit it points at, how it was named, and the name
 /// itself (a branch/tag name, or the oid string for a raw commit).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Resolved {
     /// The commit the revision resolves to.
     pub oid: Oid,
     /// How the revision was named.
     pub kind: RefKind,
     /// The human name: branch or tag name, `HEAD`, or the oid for a raw commit.
     pub name: String,
+}
 /// The kind of a tree entry.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum EntryKind {
     /// A subdirectory (another tree).
     Directory,
     /// A regular or executable file (a blob).
     File,
     /// A symbolic link (a blob whose content is the link target).
     Symlink,
     /// A submodule (a gitlink commit id).
     Submodule,
+}
 /// One entry in a tree listing.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct TreeEntry {
     /// The entry's name (the final path segment).
     pub name: String,
     /// Its kind.
     pub kind: EntryKind,
     /// The unix file mode (e.g. `0o100644`).
     pub mode: u32,
     /// The object id the entry points at.
     pub oid: Oid,
     /// The blob size in bytes, for files; `None` for directories and submodules.
     pub size: Option<u64>,
+}
 /// A blob's bytes plus the facts a view needs before deciding how to render it.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Blob {
     /// The raw content.
     pub content: Vec<u8>,
     /// Its size in bytes (`content.len()`, surfaced for convenience).
     pub size: u64,
     /// Whether the content looks binary (contains a NUL in the sniff window).
     pub is_binary: bool,
+}
 /// A person and the moment they acted, as recorded on a commit or tag.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Person {
     /// Display name.
     pub name: String,
     /// Email address.
     pub email: String,
     /// The action time, epoch milliseconds UTC.
     pub time_ms: i64,
+}
 /// A commit as shown in a log list — enough for one row.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CommitSummary {
     /// The commit id.
     pub oid: Oid,
     /// The first line of the message.
     pub summary: String,
     /// Who wrote the change.
     pub author: Person,
     /// Number of parents (0 for a root commit, ≥2 for a merge).
     pub parents: usize,
+}
 /// A commit in full, for the commit page.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CommitDetail {
     /// The commit id.
     pub oid: Oid,
     /// The complete message.
     pub message: String,
     /// Who wrote the change.
     pub author: Person,
     /// Who committed it (may differ from the author).
     pub committer: Person,
     /// The parent commit ids.
     pub parents: Vec<Oid>,
     /// The root tree id.
     pub tree: Oid,
+}
 /// A branch and its position relative to the default branch.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BranchInfo {
     /// The branch name (without the `refs/heads/` prefix).
     pub name: String,
     /// The commit it points at.
     pub oid: Oid,
     /// Whether this is the repository's default branch.
     pub is_default: bool,
     /// Commits ahead of the default branch (0 for the default branch itself).
     pub ahead: usize,
     /// Commits behind the default branch.
     pub behind: usize,
     /// The tip commit, for the "last updated" column.
     pub tip: CommitSummary,
+}
 /// A tag and what it points at.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct TagInfo {
     /// The tag name (without the `refs/tags/` prefix).
     pub name: String,
     /// The commit the tag ultimately points at (peeled).
     pub oid: Oid,
     /// Whether the tag is annotated (has its own object) vs. lightweight.
     pub annotated: bool,
     /// The annotation message, for annotated tags.
     pub message: Option<String>,
     /// The tagger, for annotated tags.
     pub tagger: Option<Person>,
+}
 /// A half-open slice of a listing: skip `offset`, take `limit`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Page {
     /// How many items to skip from the start.
     pub offset: usize,
     /// How many items to return.
     pub limit: usize,
+}
 impl Page {
     /// The first page of `limit` items.
     #[must_use]
     pub fn first(limit: usize) -> Self {
         Self { offset: 0, limit }
+    }
+}
 #[cfg(test)]
 mod tests {
     use super::*;
     #[test]
     fn oid_lowercases_and_shortens() {
         let oid = Oid::new("ABCDEF1234567890ABCDEF1234567890ABCDEF12");
         assert_eq!(oid.as_str(), "abcdef1234567890abcdef1234567890abcdef12");
         assert_eq!(oid.short(), "abcdef1");
         assert_eq!(oid.to_string(), oid.as_str());
+    }
     #[test]
     fn short_handles_undersized_ids() {
         assert_eq!(Oid::new("abc").short(), "abc");
+    }
+}