balls 0.5.12

Git-native task tracker for parallel agent workflows
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221

//! Tests for the bl-9f1d stale-read close guard — the CAS flow end to end
//! through [`crate::run`] (refuse-once-with-diff, bare-retry passes, show
//! acknowledges, prime sweeps) and the scope-by-home rungs on throwaway repos
//! (work-worktree mint, id-computed read union, the userspace-`.git` fence).

use super::*;
use crate::dispatch::support::{run_in, sole_task_id, store};
use tempfile::{tempdir, TempDir};

/// Init a plain repo at `dir` with a pinned commit identity.
fn repo(dir: &Path) {
    fs::create_dir_all(dir).unwrap();
    for args in [&["init", "-q", "-b", "main"][..], &["config", "user.name", "t"], &["config", "user.email", "t@e"]] {
        git::run(dir, args, None).unwrap();
    }
}

/// Commit `tasks/<id>.md` = `body` on `dir` with a §5 `bl-actor` trailer.
fn seal(dir: &Path, id: &str, body: &str, actor: &str) {
    fs::create_dir_all(dir.join("tasks")).unwrap();
    fs::write(dir.join("tasks").join(format!("{id}.md")), body).unwrap();
    git::run(dir, &["add", "-A"], None).unwrap();
    git::run(dir, &["commit", "-q", "-F", "-"], Some(&format!("t\n\nbl-actor: {actor}\n"))).unwrap();
}

/// A store-shaped repo whose `tasks/bl-7.md` was touched by `A` then amended
/// by `B` — the motivating race, in two commits.
fn raced_store(dir: &Path) {
    repo(dir);
    seal(dir, "bl-7", "claimed content\n", "A");
    seal(dir, "bl-7", "amended content\n", "B");
}

/// A project repo at `<tmp>/proj` with a `work/bl-7` LINKED worktree at
/// `<tmp>/bl-7` (the §11 shape: the worktree basename is the id).
fn project_with_worktree(tmp: &Path) -> (PathBuf, PathBuf) {
    let root = tmp.join("proj");
    repo(&root);
    fs::write(root.join("f"), "x").unwrap();
    git::run(&root, &["add", "-A"], None).unwrap();
    git::run(&root, &["commit", "-q", "-m", "seed"], None).unwrap();
    let wt = tmp.join("bl-7");
    git::run(&root, &["worktree", "add", "-q", "-b", "work/bl-7", &wt.to_string_lossy(), "main"], None).unwrap();
    (root, wt)
}

/// The store-clone token path for the full-run harness.
fn store_token(tmp: &TempDir, id: &str) -> PathBuf {
    gitdir(&store(tmp)).unwrap().join(TOKEN_DIR).join(id)
}

#[test]
fn a_foreign_edit_refuses_once_then_a_bare_retry_passes() {
    let tmp = TempDir::new().unwrap();
    assert_eq!(run_in(&tmp, &["prime", "--as", "me"]), 0);
    assert_eq!(run_in(&tmp, &["create", "A task", "--as", "me"]), 0);
    let id = sole_task_id(&store(&tmp).join("tasks"));
    assert_eq!(run_in(&tmp, &["claim", &id, "--as", "a"]), 0);
    assert_eq!(run_in(&tmp, &["update", &id, "note=racing", "--as", "b"]), 0);
    // The unseen edit refuses the close — and the refusal minted the token.
    assert_eq!(run_in(&tmp, &["close", &id, "--as", "a"]), 1);
    assert!(store_token(&tmp, &id).exists());
    // The bare retry seals exactly the acknowledged content and spends the token.
    assert_eq!(run_in(&tmp, &["close", &id, "--as", "a"]), 0);
    assert!(!store_token(&tmp, &id).exists());
    assert!(!store(&tmp).join("tasks").join(format!("{id}.md")).exists());
}

#[test]
fn an_edit_landing_between_refusal_and_retry_refuses_again() {
    let tmp = TempDir::new().unwrap();
    assert_eq!(run_in(&tmp, &["prime", "--as", "me"]), 0);
    assert_eq!(run_in(&tmp, &["create", "A task", "--as", "me"]), 0);
    let id = sole_task_id(&store(&tmp).join("tasks"));
    assert_eq!(run_in(&tmp, &["claim", &id, "--as", "a"]), 0);
    assert_eq!(run_in(&tmp, &["update", &id, "note=one", "--as", "b"]), 0);
    assert_eq!(run_in(&tmp, &["close", &id, "--as", "a"]), 1);
    // Yet another edit lands: the stale token must NOT pass the next close.
    assert_eq!(run_in(&tmp, &["update", &id, "note=two", "--as", "b"]), 0);
    assert_eq!(run_in(&tmp, &["close", &id, "--as", "a"]), 1);
    assert_eq!(run_in(&tmp, &["close", &id, "--as", "a"]), 0);
}

#[test]
fn a_self_edit_never_refuses_and_an_unraced_close_is_frictionless() {
    let tmp = TempDir::new().unwrap();
    assert_eq!(run_in(&tmp, &["prime", "--as", "me"]), 0);
    assert_eq!(run_in(&tmp, &["create", "A task", "--as", "me"]), 0);
    let id = sole_task_id(&store(&tmp).join("tasks"));
    assert_eq!(run_in(&tmp, &["claim", &id, "--as", "a"]), 0);
    // The closer's own update IS their last touch — zero friction (bl-9f1d).
    assert_eq!(run_in(&tmp, &["update", &id, "note=mine", "--as", "a"]), 0);
    assert_eq!(run_in(&tmp, &["close", &id, "--as", "a"]), 0);
}

#[test]
fn show_acknowledges_the_pending_edit_for_the_store_scope() {
    let tmp = TempDir::new().unwrap();
    assert_eq!(run_in(&tmp, &["prime", "--as", "me"]), 0);
    assert_eq!(run_in(&tmp, &["create", "A task", "--as", "me"]), 0);
    let id = sole_task_id(&store(&tmp).join("tasks"));
    assert_eq!(run_in(&tmp, &["claim", &id, "--as", "a"]), 0);
    assert_eq!(run_in(&tmp, &["update", &id, "note=racing", "--as", "b"]), 0);
    // The diff entered a stdout at this invocation path: close passes first try.
    assert_eq!(run_in(&tmp, &["show", &id]), 0);
    assert!(store_token(&tmp, &id).exists());
    assert_eq!(run_in(&tmp, &["close", &id, "--as", "a"]), 0);
    assert!(!store_token(&tmp, &id).exists()); // consumed by the seal
}

#[test]
fn a_dead_ball_show_mints_nothing_and_prime_sweeps_dead_tokens() {
    let tmp = TempDir::new().unwrap();
    assert_eq!(run_in(&tmp, &["prime", "--as", "me"]), 0);
    assert_eq!(run_in(&tmp, &["create", "A task", "--as", "me"]), 0);
    let id = sole_task_id(&store(&tmp).join("tasks"));
    assert_eq!(run_in(&tmp, &["close", &id, "--as", "me"]), 0);
    assert_eq!(run_in(&tmp, &["show", &id]), 0); // the dead render
    assert!(!store_token(&tmp, &id).exists()); // nothing at the tip to acknowledge
    // A live ball's token survives the sweep; a dead one's is debris.
    assert_eq!(run_in(&tmp, &["create", "B task", "--as", "me"]), 0);
    let live = sole_task_id(&store(&tmp).join("tasks"));
    assert_eq!(run_in(&tmp, &["show", &live]), 0);
    fs::write(store_token(&tmp, &id).parent().unwrap().join("bl-gone"), "feed\n").unwrap();
    assert_eq!(run_in(&tmp, &["prime", "--as", "me"]), 0);
    assert!(store_token(&tmp, &live).exists());
    assert!(!store_token(&tmp, "bl-gone").exists());
}

#[test]
fn a_closer_who_never_touched_the_ball_sees_the_whole_file_once() {
    let d = tempdir().unwrap();
    let s = d.path().join("store");
    repo(&s);
    seal(&s, "bl-7", "whole content\n", "A");
    // No anchor for C: the diff bases on the empty tree — everything is unseen.
    let err = guard(&s, d.path(), "bl-7", "C").unwrap_err().to_string();
    assert!(err.contains("changed since your last touch"), "{err}");
    assert!(err.contains("+whole content"), "{err}");
    // The refusal minted the acknowledgment: the retry passes and consumes it.
    let tokens = guard(&s, d.path(), "bl-7", "C").unwrap();
    assert_eq!(tokens.len(), 1);
    consume(&tokens);
    assert!(!tokens[0].exists());
}

#[test]
fn guard_refuses_a_store_whose_task_file_is_not_at_the_tip() {
    let d = tempdir().unwrap();
    let s = d.path().join("store");
    repo(&s);
    git::run(&s, &["commit", "-q", "--allow-empty", "-m", "root"], None).unwrap();
    fs::create_dir_all(s.join("tasks")).unwrap();
    fs::write(s.join("tasks/bl-7.md"), "uncommitted\n").unwrap();
    let err = guard(&s, d.path(), "bl-7", "A").unwrap_err().to_string();
    assert!(err.contains("not at the store tip"), "{err}");
}

#[test]
fn standing_in_a_work_worktree_mints_into_that_worktrees_own_gitdir() {
    let d = tempdir().unwrap();
    let s = d.path().join("store");
    repo(&s);
    seal(&s, "bl-7", "content\n", "A");
    let (root, wt) = project_with_worktree(d.path());
    mint(&wt, &s, "bl-7");
    let token = root.join(".git/worktrees/bl-7").join(TOKEN_DIR).join("bl-7");
    assert!(token.exists(), "per-agent scope: the mint home is the worktree gitdir");
    assert!(!gitdir(&s).unwrap().join(TOKEN_DIR).join("bl-7").exists());
}

#[test]
fn a_worktree_minted_token_is_read_from_the_repo_root_by_id() {
    let d = tempdir().unwrap();
    let s = d.path().join("store");
    raced_store(&s);
    let (root, wt) = project_with_worktree(d.path());
    // The claimant saw the amendment from INSIDE their worktree; the close runs
    // from the repo root — the union computes the worktree rung from the id.
    mint(&wt, &s, "bl-7");
    let tokens = guard(&s, &root, "bl-7", "A").unwrap();
    assert_eq!(tokens, vec![root.join(".git/worktrees/bl-7").join(TOKEN_DIR).join("bl-7")]);
}

#[test]
fn the_union_dedups_when_standing_in_the_tasks_own_worktree() {
    let d = tempdir().unwrap();
    let s = d.path().join("store");
    repo(&s);
    seal(&s, "bl-7", "content\n", "A");
    let (root, wt) = project_with_worktree(d.path());
    // Current-worktree rung == the id-computed rung: one entry, not two.
    let homes = union(&s, &wt, "bl-7").unwrap();
    assert_eq!(homes, vec![gitdir(&s).unwrap(), root.join(".git/worktrees/bl-7")]);
}

#[test]
fn a_work_branch_at_the_repo_root_is_not_bl_territory() {
    let d = tempdir().unwrap();
    let s = d.path().join("store");
    repo(&s);
    seal(&s, "bl-7", "content\n", "A");
    let root = d.path().join("proj");
    repo(&root);
    fs::write(root.join("f"), "x").unwrap();
    git::run(&root, &["add", "-A"], None).unwrap();
    git::run(&root, &["commit", "-q", "-m", "seed"], None).unwrap();
    // A `work/` branch checked out at the ROOT: gitdir == common dir, so the
    // mint falls to the store rung — bl never writes the userspace `.git`.
    git::run(&root, &["switch", "-q", "-c", "work/bl-7"], None).unwrap();
    mint(&root, &s, "bl-7");
    assert!(!root.join(".git").join(TOKEN_DIR).join("bl-7").exists());
    assert!(gitdir(&s).unwrap().join(TOKEN_DIR).join("bl-7").exists());
}

#[test]
fn gitdir_refuses_a_non_repo_store() {
    let d = tempdir().unwrap();
    let err = gitdir(d.path()).unwrap_err().to_string();
    assert!(err.contains("not a git checkout"), "{err}");
}