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
//! Keep tm-regenerated harness scaffolding out of a project's git history
//! (issue #3427).
//!
//! Why: `tm` writes composed agents (`.claude/agents/`), skills
//! (`.claude/skills/`), and output styles (`.claude/output-styles/`) directly
//! into a project's working tree — a managed workspace deploys all three
//! project-locally, and the `#2125` project-tier output-style deploy runs
//! unconditionally for every session regardless of managed/standalone. If a
//! project ever commits one of those paths (accidentally, in a PR, or from a
//! pre-#3427 install with no `.gitignore` guard), the NEXT session's
//! regeneration writes the same path back as local content — and a later
//! `git merge --ff-only origin/main` aborts with "your local changes would be
//! overwritten", exactly the `duettoresearch/duetto-eve-agents` reproduction
//! (28 commits stranded, resolved only by `git rm -r --cached` + a manual
//! `.gitignore`, duetto-eve-agents#111). This is Option 1 (prevent) of #3427;
//! [`crate::daemon::doctor_scaffold_tracking`] is Option 2 (detect + exact
//! remediation for a project that already committed these paths — a
//! `.gitignore` entry added AFTER the fact does not untrack anything already
//! in the index).
//! What: [`ensure_scaffold_gitignored`] appends a small, clearly-delimited
//! managed block to `<project_dir>/.gitignore` naming exactly the three
//! harness-owned subdirectories tm writes into — never the broader
//! `.claude/` (which also holds `settings.json` / project `.mcp.json`,
//! legitimately shared config the issue explicitly calls out as NOT in
//! scope). Gated on `project_dir` actually being a git working tree (a
//! `.git` entry present) — mirroring the existing
//! `daemon::managed_routes::inproject::ensure_worktrees_gitignored`
//! precedent — so a non-git project (or a bare library/test call) never
//! grows a stray `.gitignore`. Idempotent: a repeat call is a no-op once the
//! managed block's begin marker is present, and an existing `.gitignore`
//! with unrelated content is preserved byte-for-byte apart from the
//! appended block. This only edits the WORKING TREE file — it never `git
//! add`s or commits it, so the change goes through the project's normal
//! review/diff flow like any other tm-authored edit.
//! Test: `writes_block_to_fresh_gitignore`, `idempotent_on_repeat_call`,
//! `preserves_unrelated_existing_content`, `noop_when_not_a_git_repo`,
//! `appends_newline_when_existing_file_lacks_trailing_newline`.
use std::io::Write as _;
use std::path::Path;
/// First line of the managed block — its presence is the sole idempotency
/// check (a repeat call skips entirely once this line exists anywhere in the
/// file).
pub const SCAFFOLD_GITIGNORE_BEGIN: &str =
"# >>> trusty-mpm harness scaffolding (auto-managed by tm, issue #3427) >>>";
/// Last line of the managed block.
pub const SCAFFOLD_GITIGNORE_END: &str = "# <<< trusty-mpm harness scaffolding <<<";
/// The exact harness-owned subdirectories tm writes into, and nothing else.
///
/// Why: surgical by design — `.claude/settings.json` and the project
/// `.mcp.json` are legitimately shared, tracked config (issue #3427's
/// explicit "Important Note") and must never be swept up by this list.
/// What: trailing-slash directory patterns so only the three harness-owned
/// subtrees are ignored, not sibling files under `.claude/`.
pub const SCAFFOLD_IGNORED_PATHS: &[&str] = &[
".claude/agents/",
".claude/skills/",
".claude/output-styles/",
];
/// Ensure `<project_dir>/.gitignore` carries the tm-scaffolding managed
/// block, when `project_dir` is a git working tree.
///
/// Why/What: see the module doc. Returns `Ok(true)` when the block was
/// (freshly) written, `Ok(false)` when it was already present or
/// `project_dir` is not a git repo (both are legitimate no-ops, not
/// failures). Propagates genuine I/O errors (permissions, disk full) so the
/// non-fatal caller can log them rather than silently swallowing a real
/// problem.
/// Test: `writes_block_to_fresh_gitignore`, `idempotent_on_repeat_call`,
/// `preserves_unrelated_existing_content`, `noop_when_not_a_git_repo`.
pub fn ensure_scaffold_gitignored(project_dir: &Path) -> std::io::Result<bool> {
if !project_dir.join(".git").exists() {
return Ok(false);
}
let gitignore_path = project_dir.join(".gitignore");
let existing = std::fs::read_to_string(&gitignore_path).unwrap_or_default();
// Idempotent: the begin marker's presence anywhere in the file means a
// prior run already installed the block — never append a duplicate.
if existing
.lines()
.any(|line| line == SCAFFOLD_GITIGNORE_BEGIN)
{
return Ok(false);
}
let mut block = String::new();
if !existing.is_empty() && !existing.ends_with('\n') {
block.push('\n');
}
if !existing.is_empty() {
block.push('\n');
}
block.push_str(SCAFFOLD_GITIGNORE_BEGIN);
block.push('\n');
for path in SCAFFOLD_IGNORED_PATHS {
block.push_str(path);
block.push('\n');
}
block.push_str(SCAFFOLD_GITIGNORE_END);
block.push('\n');
let mut file = std::fs::OpenOptions::new()
.create(true)
.append(true)
.open(&gitignore_path)?;
file.write_all(block.as_bytes())?;
tracing::info!(
path = %gitignore_path.display(),
"added tm harness-scaffolding block to .gitignore (issue #3427)"
);
Ok(true)
}
#[cfg(test)]
mod tests {
use super::*;
fn init_git_repo(dir: &Path) {
std::fs::create_dir_all(dir.join(".git")).unwrap();
}
#[test]
fn writes_block_to_fresh_gitignore() {
let tmp = crate::test_support::hermetic_temp_dir();
init_git_repo(tmp.path());
let wrote = ensure_scaffold_gitignored(tmp.path()).unwrap();
assert!(wrote, "first call must write the block");
let content = std::fs::read_to_string(tmp.path().join(".gitignore")).unwrap();
assert!(content.contains(SCAFFOLD_GITIGNORE_BEGIN));
assert!(content.contains(SCAFFOLD_GITIGNORE_END));
for path in SCAFFOLD_IGNORED_PATHS {
assert!(
content.contains(path),
"missing {path} in written .gitignore:\n{content}"
);
}
// Never blanket-ignore `.claude/` itself — settings.json / .mcp.json
// must remain trackable.
assert!(!content.lines().any(|l| l.trim() == ".claude/"));
}
#[test]
fn idempotent_on_repeat_call() {
let tmp = crate::test_support::hermetic_temp_dir();
init_git_repo(tmp.path());
assert!(ensure_scaffold_gitignored(tmp.path()).unwrap());
let first = std::fs::read_to_string(tmp.path().join(".gitignore")).unwrap();
// A second (and third) call must be a no-op — no duplicated block.
assert!(!ensure_scaffold_gitignored(tmp.path()).unwrap());
assert!(!ensure_scaffold_gitignored(tmp.path()).unwrap());
let second = std::fs::read_to_string(tmp.path().join(".gitignore")).unwrap();
assert_eq!(first, second, "repeat calls must not modify the file");
assert_eq!(
second.matches(SCAFFOLD_GITIGNORE_BEGIN).count(),
1,
"the begin marker must appear exactly once"
);
}
#[test]
fn preserves_unrelated_existing_content() {
let tmp = crate::test_support::hermetic_temp_dir();
init_git_repo(tmp.path());
let gitignore_path = tmp.path().join(".gitignore");
std::fs::write(&gitignore_path, "node_modules/\ntarget/\n").unwrap();
ensure_scaffold_gitignored(tmp.path()).unwrap();
let content = std::fs::read_to_string(&gitignore_path).unwrap();
assert!(content.starts_with("node_modules/\ntarget/\n"));
assert!(content.contains(SCAFFOLD_GITIGNORE_BEGIN));
}
#[test]
fn appends_newline_when_existing_file_lacks_trailing_newline() {
let tmp = crate::test_support::hermetic_temp_dir();
init_git_repo(tmp.path());
let gitignore_path = tmp.path().join(".gitignore");
// Deliberately no trailing newline.
std::fs::write(&gitignore_path, "node_modules/").unwrap();
ensure_scaffold_gitignored(tmp.path()).unwrap();
let content = std::fs::read_to_string(&gitignore_path).unwrap();
assert!(content.starts_with("node_modules/\n"));
assert!(
!content.contains("node_modules/#"),
"must not glue lines together"
);
}
#[test]
fn noop_when_not_a_git_repo() {
let tmp = crate::test_support::hermetic_temp_dir();
// No `.git` created.
let wrote = ensure_scaffold_gitignored(tmp.path()).unwrap();
assert!(!wrote, "must not write when project_dir is not a git repo");
assert!(!tmp.path().join(".gitignore").exists());
}
}