Build AgentGuide — versioned CLAUDE.md maintenance
The app-owned agent guide at every board root (DESIGN/08 ▸ The agent guide): version-gated by a first-line marker (v5, superseding the pathfinder's v4 guides on real boards), rewritten when missing or older, byte-for-byte untouched when current or newer. A markerless CLAUDE.md is displaced to CLAUDE.user.md when that name is free — never clobbered — and the guide write is skipped with a log when it isn't. Symlinks, folders, and read-only volumes are skipped in silence; the write rides performWrite's bracket as an app-mediated Writer operation (new WriteOperation.agentGuide), so the echo lands appMediated and the Pro-era committer can attribute it honestly later. Hooked at store acquire (beside the loose-file relocation, after the watcher exists) and on every successful reload — the guide self-heals from foreign deletion or rollback, pre-wiring 06's acknowledged undo bounce. The refresh memo arms before each attempt and clears on a successful write, so a failing write can't hot-loop and a foreign deletion stays healable. First-line-only marker parsing (no Regex); guide content is one swappable literal, finalized under the next card. Claude-Session: https://claude.ai/code/session_01SR4XGjmBE16ZUYWpfFHXwY
This commit is contained in:
@@ -0,0 +1,570 @@
|
||||
import Foundation
|
||||
import Testing
|
||||
@testable import Kanban
|
||||
|
||||
/// The agent guide, end to end (08-agent-integration.md ▸ The agent guide).
|
||||
///
|
||||
/// The rule is three promises, and this file is organized as them:
|
||||
///
|
||||
/// 1. **The marker decides, and only the first line carries it** — the version gate, parsed as a
|
||||
/// pure function of text.
|
||||
/// 2. **The decision is pure** — write, leave alone, displace, or skip, from what the two claimed
|
||||
/// board-root names look like on disk and nothing else.
|
||||
/// 3. **Nothing the user owns is ever destroyed** — a markerless `CLAUDE.md` is rescued, a taken
|
||||
/// `CLAUDE.user.md` cancels the write outright, a symlink or a folder is not touched at all, and
|
||||
/// a current guide is not even opened for writing.
|
||||
///
|
||||
/// Every on-disk claim is read back as **raw bytes**, never through a snapshot: the promises are
|
||||
/// about the files. `WriterFixture`, `Ident` and `Item` come from `WriterTestSupport.swift`.
|
||||
|
||||
// MARK: - Shared fixtures
|
||||
|
||||
/// A one-lane board — enough tree that a reload has something to walk.
|
||||
@MainActor
|
||||
private func makeBoard() throws -> WriterFixture {
|
||||
let fixture = try WriterFixture()
|
||||
try fixture.item("", Item.board)
|
||||
try fixture.item(Ident.lane1, Item.rich(order: "1024", title: "Todo"))
|
||||
return fixture
|
||||
}
|
||||
|
||||
/// A guide-shaped file at some version — the shape an older app version left behind, or one a newer
|
||||
/// version will.
|
||||
private func guideText(version: Int) -> String {
|
||||
"<!-- lanework-agent-guide v\(version) — created and kept up to date by the Lanework app. -->\n\n# This folder is a Lanework kanban board\n"
|
||||
}
|
||||
|
||||
/// A file's bytes and mtime — "this file was not rewritten", stated the way `LooseFileRelocationTests`
|
||||
/// states it.
|
||||
private func stat(_ url: URL) throws -> (bytes: Data, modified: Date) {
|
||||
let attributes = try FileManager.default.attributesOfItem(atPath: url.path)
|
||||
guard let modified = attributes[.modificationDate] as? Date else {
|
||||
throw NSError(domain: "AgentGuideTests", code: 1)
|
||||
}
|
||||
return (try Data(contentsOf: url), modified)
|
||||
}
|
||||
|
||||
private func guideURL(in fixture: WriterFixture) -> URL {
|
||||
fixture.root.appendingPathComponent(AgentGuide.filename)
|
||||
}
|
||||
|
||||
private func userFileURL(in fixture: WriterFixture) -> URL {
|
||||
fixture.root.appendingPathComponent(AgentGuide.userFilename)
|
||||
}
|
||||
|
||||
/// Writes raw bytes to one of the two claimed board-root names, without going near the app.
|
||||
@discardableResult
|
||||
private func writeRoot(_ name: String, _ bytes: Data, in fixture: WriterFixture) throws -> URL {
|
||||
let url = fixture.root.appendingPathComponent(name)
|
||||
try bytes.write(to: url)
|
||||
return url
|
||||
}
|
||||
|
||||
/// Counts the bracket calls a store makes, standing in for the watcher the registry wires up.
|
||||
@MainActor
|
||||
private final class GuideBracketLog {
|
||||
private(set) var begins = 0
|
||||
|
||||
func attach(to store: BoardStore) {
|
||||
store.watcherBrackets = (begin: { self.begins += 1 }, end: {})
|
||||
}
|
||||
}
|
||||
|
||||
/// Polls until `condition` holds or the deadline passes — generous, because FSEvents delivery is not
|
||||
/// a bounded-latency promise (`BoardStoreRegistryTests`' idiom).
|
||||
@MainActor
|
||||
private func waitUntil(_ deadline: Duration = .seconds(15), _ condition: () -> Bool) async {
|
||||
let start = ContinuousClock.now
|
||||
while ContinuousClock.now - start < deadline {
|
||||
if condition() { return }
|
||||
try? await Task.sleep(for: .milliseconds(25))
|
||||
}
|
||||
}
|
||||
|
||||
/// Gives a freshly started stream a beat to register with `fseventsd` — see `FolderWatcherTests`.
|
||||
@MainActor
|
||||
private func settle() async {
|
||||
try? await Task.sleep(for: .milliseconds(300))
|
||||
}
|
||||
|
||||
// MARK: - 1. The version marker
|
||||
|
||||
@Suite("Agent guide ▸ the marker")
|
||||
struct AgentGuideMarkerTests {
|
||||
|
||||
@Test("The guide the app ships carries the current marker in its first line")
|
||||
func shippedGuideCarriesTheMarker() {
|
||||
let firstLine = String(AgentGuide.content.prefix { !$0.isNewline })
|
||||
#expect(firstLine.contains("lanework-agent-guide v5"))
|
||||
#expect(AgentGuide.installedVersion(of: AgentGuide.content) == AgentGuide.version)
|
||||
// Files the app creates end with LF (01-storage-format.md § Encoding and line endings).
|
||||
#expect(AgentGuide.content.hasSuffix("\n"))
|
||||
#expect(!AgentGuide.content.hasSuffix("\n\n"))
|
||||
}
|
||||
|
||||
@Test("Any version in the first line parses")
|
||||
func versionsParse() {
|
||||
#expect(AgentGuide.installedVersion(of: guideText(version: 1)) == 1)
|
||||
#expect(AgentGuide.installedVersion(of: guideText(version: 4)) == 4)
|
||||
#expect(AgentGuide.installedVersion(of: guideText(version: 12)) == 12)
|
||||
}
|
||||
|
||||
@Test("A file with no marker has no version")
|
||||
func markerlessHasNoVersion() {
|
||||
#expect(AgentGuide.installedVersion(of: "# My project\n\nNotes for agents.\n") == nil)
|
||||
#expect(AgentGuide.installedVersion(of: "") == nil)
|
||||
// The prefix without a number is not a marker either.
|
||||
#expect(AgentGuide.installedVersion(of: "lanework-agent-guide vNext\n") == nil)
|
||||
}
|
||||
|
||||
/// **The deliberate divergence from the pathfinder** (08: "version marker in the first line"):
|
||||
/// a user's own file that merely *quotes* the marker further down is not an app-owned guide, and
|
||||
/// reading it as one would overwrite it.
|
||||
@Test("A marker below the first line does not count")
|
||||
func markerBelowTheFirstLineIsNotAMarker() {
|
||||
#expect(AgentGuide.installedVersion(of: "# Notes\nlanework-agent-guide v5\n") == nil)
|
||||
#expect(AgentGuide.installedVersion(of: "\nlanework-agent-guide v9\n") == nil)
|
||||
}
|
||||
|
||||
@Test("CRLF and a missing final newline both parse")
|
||||
func lineEndingsDoNotMatter() {
|
||||
#expect(AgentGuide.installedVersion(of: "<!-- lanework-agent-guide v3 -->\r\nbody\r\n") == 3)
|
||||
#expect(AgentGuide.installedVersion(of: "<!-- lanework-agent-guide v3 -->") == 3)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - 2. The decision
|
||||
|
||||
@Suite("Agent guide ▸ the decision")
|
||||
struct AgentGuideDecisionTests {
|
||||
|
||||
private func state(_ existing: AgentGuide.Existing, userFileFree: Bool = true) -> AgentGuide.State {
|
||||
AgentGuide.State(existing: existing, userFilenameIsFree: userFileFree)
|
||||
}
|
||||
|
||||
@Test("Missing writes; older rewrites")
|
||||
func missingAndOlderWrite() {
|
||||
#expect(AgentGuide.decide(state(.missing)) == .write)
|
||||
#expect(AgentGuide.decide(state(.file(text: guideText(version: 1)))) == .write)
|
||||
#expect(AgentGuide.decide(state(.file(text: guideText(version: 4)))) == .write)
|
||||
}
|
||||
|
||||
/// "Never downgraded" — a newer app version may have written it.
|
||||
@Test("Current and newer are left alone")
|
||||
func currentAndNewerAreLeftAlone() {
|
||||
#expect(AgentGuide.decide(state(.file(text: guideText(version: 5)))) == .leaveAlone)
|
||||
#expect(AgentGuide.decide(state(.file(text: guideText(version: 6)))) == .leaveAlone)
|
||||
#expect(AgentGuide.decide(state(.file(text: AgentGuide.content))) == .leaveAlone)
|
||||
}
|
||||
|
||||
@Test("A markerless file is displaced when the user name is free")
|
||||
func markerlessIsDisplaced() {
|
||||
#expect(AgentGuide.decide(state(.file(text: "# My own notes\n"))) == .displaceThenWrite)
|
||||
// Undecodable bytes are markerless too — the move preserves them either way.
|
||||
#expect(AgentGuide.decide(state(.file(text: nil))) == .displaceThenWrite)
|
||||
// A marker that is not on the first line is a user file, not an old guide.
|
||||
#expect(AgentGuide.decide(state(.file(text: "# Notes\nlanework-agent-guide v4\n"))) == .displaceThenWrite)
|
||||
}
|
||||
|
||||
/// "Otherwise the guide write is skipped with a log — user content is never destroyed."
|
||||
@Test("A taken CLAUDE.user.md cancels the write outright")
|
||||
func takenUserFilenameSkips() {
|
||||
#expect(AgentGuide.decide(state(.file(text: "# My own notes\n"), userFileFree: false)) == .skipUserFilenameTaken)
|
||||
#expect(AgentGuide.decide(state(.file(text: nil), userFileFree: false)) == .skipUserFilenameTaken)
|
||||
// It has no bearing on the version gate: an app-owned guide is still upgraded in place.
|
||||
#expect(AgentGuide.decide(state(.file(text: guideText(version: 4)), userFileFree: false)) == .write)
|
||||
#expect(AgentGuide.decide(state(.missing, userFileFree: false)) == .write)
|
||||
}
|
||||
|
||||
@Test("A symlink or a folder is never touched, free name or not")
|
||||
func untouchableIsSkipped() {
|
||||
#expect(AgentGuide.decide(state(.untouchable)) == .skipUntouchable)
|
||||
#expect(AgentGuide.decide(state(.untouchable, userFileFree: false)) == .skipUntouchable)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - 3. On disk, through the store
|
||||
|
||||
@MainActor
|
||||
@Suite("Agent guide ▸ on disk")
|
||||
struct AgentGuideStoreTests {
|
||||
|
||||
@Test("A board with no CLAUDE.md gets the current guide")
|
||||
func missingGuideIsWritten() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
let brackets = GuideBracketLog()
|
||||
brackets.attach(to: store)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
let written = try String(decoding: fixture.data(AgentGuide.filename), as: UTF8.self)
|
||||
#expect(written.prefix { !$0.isNewline }.contains("lanework-agent-guide v5"))
|
||||
#expect(written == AgentGuide.content)
|
||||
#expect(!fixture.exists(AgentGuide.userFilename))
|
||||
#expect(brackets.begins == 1, "one bracket — one app-mediated reload, one commit")
|
||||
// A courtesy file the user never asked for has nothing to say to them.
|
||||
#expect(store.banners.oneShots.isEmpty)
|
||||
#expect(store.banners.losses.isEmpty)
|
||||
// No temp-file residue from the atomic replace.
|
||||
#expect(try fixture.entryNames("").contains(AgentGuide.filename))
|
||||
#expect(try !fixture.entryNames("").contains { $0.hasPrefix(".\(AgentGuide.filename)") })
|
||||
}
|
||||
|
||||
@Test("An older guide is rewritten to the current one")
|
||||
func olderGuideIsUpgraded() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
try writeRoot(AgentGuide.filename, Data(guideText(version: 4).utf8), in: fixture)
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
#expect(try fixture.data(AgentGuide.filename) == Data(AgentGuide.content.utf8))
|
||||
// An upgrade is not a displacement: nothing was rescued, because nothing was the user's.
|
||||
#expect(!fixture.exists(AgentGuide.userFilename))
|
||||
}
|
||||
|
||||
/// "Left untouched when current or newer" — and untouched means the file is not even opened for
|
||||
/// writing, so its mtime (and, on git boards, the tree) is undisturbed.
|
||||
@Test("A current guide is left byte-for-byte alone, mtime included")
|
||||
func currentGuideIsNotRewritten() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
// Deliberately *not* the app's own text: a v5 marker is the whole gate, and a file carrying
|
||||
// one must survive verbatim even when its body differs from what this version would write.
|
||||
let url = try writeRoot(AgentGuide.filename, Data(guideText(version: 5).utf8), in: fixture)
|
||||
let before = try stat(url)
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
let brackets = GuideBracketLog()
|
||||
brackets.attach(to: store)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
let after = try stat(url)
|
||||
#expect(after.bytes == before.bytes)
|
||||
#expect(after.modified == before.modified)
|
||||
#expect(brackets.begins == 0, "no write means no bracket and no commit")
|
||||
}
|
||||
|
||||
@Test("A newer guide is never downgraded")
|
||||
func newerGuideIsNotDowngraded() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let url = try writeRoot(AgentGuide.filename, Data(guideText(version: 99).utf8), in: fixture)
|
||||
let before = try stat(url)
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
let after = try stat(url)
|
||||
#expect(after.bytes == before.bytes)
|
||||
#expect(after.modified == before.modified)
|
||||
}
|
||||
|
||||
@Test("A markerless CLAUDE.md moves to CLAUDE.user.md, byte for byte, and the guide takes its place")
|
||||
func markerlessIsDisplaced() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let mine = "# Board rules\n\nAlways file bugs in the Triage lane.\n"
|
||||
try writeRoot(AgentGuide.filename, Data(mine.utf8), in: fixture)
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
let brackets = GuideBracketLog()
|
||||
brackets.attach(to: store)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
#expect(try fixture.data(AgentGuide.userFilename) == Data(mine.utf8))
|
||||
#expect(try fixture.data(AgentGuide.filename) == Data(AgentGuide.content.utf8))
|
||||
#expect(brackets.begins == 1, "the rescue and the write ride one bracket")
|
||||
#expect(store.banners.oneShots.isEmpty)
|
||||
}
|
||||
|
||||
/// The first-line rule, proved where it costs something: a user file quoting the marker is
|
||||
/// rescued, not overwritten.
|
||||
@Test("A marker below the first line is user content and is displaced")
|
||||
func markerBelowTheFirstLineIsDisplaced() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let mine = "# Notes about Lanework\n\nThe app stamps `lanework-agent-guide v5` into CLAUDE.md.\n"
|
||||
try writeRoot(AgentGuide.filename, Data(mine.utf8), in: fixture)
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
#expect(try fixture.data(AgentGuide.userFilename) == Data(mine.utf8))
|
||||
#expect(try fixture.data(AgentGuide.filename) == Data(AgentGuide.content.utf8))
|
||||
}
|
||||
|
||||
@Test("A CLAUDE.md that is not UTF-8 is displaced with its bytes intact")
|
||||
func undecodableIsDisplacedByteForByte() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let bytes = Data([0xFF, 0xFE, 0x00, 0x41, 0x80, 0x0A])
|
||||
try writeRoot(AgentGuide.filename, bytes, in: fixture)
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
#expect(try fixture.data(AgentGuide.userFilename) == bytes)
|
||||
#expect(try fixture.data(AgentGuide.filename) == Data(AgentGuide.content.utf8))
|
||||
}
|
||||
|
||||
/// "Otherwise the guide write is skipped with a log — user content is never destroyed." Two
|
||||
/// files the user owns, both still theirs afterwards, and no guide on this board at all.
|
||||
@Test("A taken CLAUDE.user.md leaves both files alone and writes no guide")
|
||||
func takenUserFilenameSkipsTheWrite() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let mine = "# Board rules\n"
|
||||
let theirs = "# Older board rules\n"
|
||||
let guide = try writeRoot(AgentGuide.filename, Data(mine.utf8), in: fixture)
|
||||
let user = try writeRoot(AgentGuide.userFilename, Data(theirs.utf8), in: fixture)
|
||||
let guideBefore = try stat(guide)
|
||||
let userBefore = try stat(user)
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
let brackets = GuideBracketLog()
|
||||
brackets.attach(to: store)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
#expect(try stat(guide).bytes == guideBefore.bytes)
|
||||
#expect(try stat(guide).modified == guideBefore.modified)
|
||||
#expect(try stat(user).bytes == userBefore.bytes)
|
||||
#expect(try stat(user).modified == userBefore.modified)
|
||||
#expect(brackets.begins == 0)
|
||||
#expect(store.banners.oneShots.isEmpty, "a skip is a log line, not a banner")
|
||||
}
|
||||
|
||||
/// Symlinks are never followed or touched anywhere in this app (01-storage-format.md § Fractal
|
||||
/// layout ▸ Rules) — including one wearing the guide's name.
|
||||
@Test("A symlinked CLAUDE.md is left as a symlink, and its target is untouched")
|
||||
func symlinkedGuideIsSkipped() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let target = try fixture.file("elsewhere.md", Data("# somewhere else\n".utf8))
|
||||
try FileManager.default.createSymbolicLink(atPath: guideURL(in: fixture).path, withDestinationPath: "elsewhere.md")
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
let destination = try FileManager.default.destinationOfSymbolicLink(atPath: guideURL(in: fixture).path)
|
||||
#expect(destination == "elsewhere.md", "the link is still a link")
|
||||
#expect(try Data(contentsOf: target) == Data("# somewhere else\n".utf8), "and it was not written through")
|
||||
#expect(!fixture.exists(AgentGuide.userFilename))
|
||||
}
|
||||
|
||||
/// The rescue name is checked with `lstat` semantics, so a **broken** symlink counts as taken:
|
||||
/// `fileExists` would follow it, find nothing, call the name free — and the move would then fail
|
||||
/// into a banner about a file the user never asked for.
|
||||
@Test("A dangling symlink on CLAUDE.user.md counts as taken")
|
||||
func danglingRescueNameIsTaken() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
try writeRoot(AgentGuide.filename, Data("# mine\n".utf8), in: fixture)
|
||||
try FileManager.default.createSymbolicLink(atPath: userFileURL(in: fixture).path, withDestinationPath: "nowhere.md")
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
#expect(try fixture.data(AgentGuide.filename) == Data("# mine\n".utf8))
|
||||
#expect(try FileManager.default.destinationOfSymbolicLink(atPath: userFileURL(in: fixture).path) == "nowhere.md")
|
||||
#expect(store.banners.oneShots.isEmpty)
|
||||
}
|
||||
|
||||
/// A regular file the app cannot *read* is markerless, not missing — so it is displaced, never
|
||||
/// overwritten. The move preserves it without ever needing to read it.
|
||||
@Test("An unreadable CLAUDE.md is displaced, not clobbered")
|
||||
func unreadableGuideIsDisplaced() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let url = try writeRoot(AgentGuide.filename, Data("# secret\n".utf8), in: fixture)
|
||||
try FileManager.default.setAttributes([.posixPermissions: 0o000], ofItemAtPath: url.path)
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
#expect(try fixture.data(AgentGuide.filename) == Data(AgentGuide.content.utf8))
|
||||
try FileManager.default.setAttributes([.posixPermissions: 0o644], ofItemAtPath: userFileURL(in: fixture).path)
|
||||
#expect(try fixture.data(AgentGuide.userFilename) == Data("# secret\n".utf8))
|
||||
}
|
||||
|
||||
@Test("A folder named CLAUDE.md is left alone")
|
||||
func directoryGuideIsSkipped() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
try fixture.file("\(AgentGuide.filename)/inside.txt", Data("inside".utf8))
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
#expect(try fixture.data("\(AgentGuide.filename)/inside.txt") == Data("inside".utf8))
|
||||
#expect(!fixture.exists(AgentGuide.userFilename))
|
||||
}
|
||||
|
||||
/// 02-architecture.md § Write-failure surfacing: "The open-time agent-guide write … is
|
||||
/// skipped-with-log, the `CLAUDE.user.md`-taken precedent." A board on a read-only volume must
|
||||
/// not spend a banner on a courtesy file.
|
||||
@Test("An unwritable board root is skipped silently")
|
||||
func unwritableRootIsSkipped() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
let brackets = GuideBracketLog()
|
||||
brackets.attach(to: store)
|
||||
// Readable (so the board still loads and renders) but not writable.
|
||||
try FileManager.default.setAttributes([.posixPermissions: 0o500], ofItemAtPath: fixture.root.path)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
|
||||
#expect(!fixture.exists(AgentGuide.filename))
|
||||
#expect(brackets.begins == 0)
|
||||
#expect(store.banners.oneShots.isEmpty)
|
||||
}
|
||||
|
||||
/// The read-only *lock* defers it as well — the relocation's posture, and 02's.
|
||||
@Test("A read-only-locked board defers, and writes the guide when the lock clears")
|
||||
func lockedBoardDefers() async throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
store.enterUnwritableLock()
|
||||
|
||||
store.refreshAgentGuide()
|
||||
#expect(!fixture.exists(AgentGuide.filename))
|
||||
|
||||
// A reconciling reload re-probes writability, the lock clears — and the same reload writes
|
||||
// the guide it had been holding back.
|
||||
store.handleWatcherEvent(.treeChanged(.reconciling))
|
||||
await store.awaitQuiescence()
|
||||
|
||||
#expect(!store.isReadOnly)
|
||||
#expect(try fixture.data(AgentGuide.filename) == Data(AgentGuide.content.utf8))
|
||||
}
|
||||
|
||||
@Test("Refreshing twice writes once")
|
||||
func secondRefreshIsANoOp() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
let brackets = GuideBracketLog()
|
||||
brackets.attach(to: store)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
let after = try stat(guideURL(in: fixture))
|
||||
store.refreshAgentGuide()
|
||||
|
||||
#expect(try stat(guideURL(in: fixture)).modified == after.modified)
|
||||
#expect(brackets.begins == 1)
|
||||
}
|
||||
|
||||
/// The self-heal, stated where it is deterministic: every successful reload re-checks the guide,
|
||||
/// so a foreign deletion or downgrade is repaired by the reload that noticed it.
|
||||
@Test("A reload re-checks the guide — a deleted one comes back")
|
||||
func aReloadHealsIt() async throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
store.refreshAgentGuide()
|
||||
try FileManager.default.removeItem(at: guideURL(in: fixture))
|
||||
|
||||
store.handleWatcherEvent(.treeChanged(.foreign))
|
||||
await store.awaitQuiescence()
|
||||
|
||||
#expect(try fixture.data(AgentGuide.filename) == Data(AgentGuide.content.utf8))
|
||||
}
|
||||
|
||||
/// The memo `refreshAgentGuide()` documents, from both sides: a picture this store has already
|
||||
/// refused to act on is not acted on again by every reload that re-reads it, and a picture that
|
||||
/// genuinely *changed* is a fresh attempt.
|
||||
@Test("A skipped board stays skipped across reloads, and heals when the name frees up")
|
||||
func aSkipIsNotRetriedUntilThePictureChanges() async throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
// A *folder* on the rescue name is exactly as taken as a file — the app never descends into
|
||||
// one, renames around it, or overwrites it.
|
||||
try writeRoot(AgentGuide.filename, Data("# mine\n".utf8), in: fixture)
|
||||
try fixture.file("\(AgentGuide.userFilename)/inside.txt", Data("inside".utf8))
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
let brackets = GuideBracketLog()
|
||||
brackets.attach(to: store)
|
||||
|
||||
store.refreshAgentGuide()
|
||||
for _ in 0 ..< 3 {
|
||||
store.handleWatcherEvent(.treeChanged(.foreign))
|
||||
await store.awaitQuiescence()
|
||||
}
|
||||
|
||||
#expect(brackets.begins == 0, "no write was ever attempted")
|
||||
#expect(store.banners.oneShots.isEmpty, "and no row was posted, once or four times")
|
||||
#expect(try fixture.data(AgentGuide.filename) == Data("# mine\n".utf8))
|
||||
#expect(try fixture.data("\(AgentGuide.userFilename)/inside.txt") == Data("inside".utf8))
|
||||
|
||||
// The name frees up: a different picture, so a fresh attempt — and the rescue finally runs.
|
||||
try FileManager.default.removeItem(at: userFileURL(in: fixture))
|
||||
store.handleWatcherEvent(.treeChanged(.foreign))
|
||||
await store.awaitQuiescence()
|
||||
|
||||
#expect(try fixture.data(AgentGuide.userFilename) == Data("# mine\n".utf8))
|
||||
#expect(try fixture.data(AgentGuide.filename) == Data(AgentGuide.content.utf8))
|
||||
#expect(brackets.begins == 1)
|
||||
}
|
||||
|
||||
@Test("The guide is not a stray, and does not disturb the load")
|
||||
func guideIsNotAStray() throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let store = try BoardStore(rootURL: fixture.root)
|
||||
store.refreshAgentGuide()
|
||||
try writeRoot(AgentGuide.userFilename, Data("# mine\n".utf8), in: fixture)
|
||||
|
||||
let result = try BoardLoader.load(boardRoot: fixture.root)
|
||||
#expect(result.warnings.isEmpty, "both names are app-claimed, never stray-warned")
|
||||
#expect(result.model.lanes.count == 1)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - 4. Through the registry, with a real watcher
|
||||
|
||||
@MainActor
|
||||
@Suite("Agent guide ▸ the registry")
|
||||
struct AgentGuideRegistryTests {
|
||||
|
||||
/// The open-time firing, wired the way the app wires it — after the watcher and the brackets
|
||||
/// exist, so the write has a reload behind it.
|
||||
@Test("Acquiring a board writes the guide")
|
||||
func acquireWritesTheGuide() async throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let registry = BoardStoreRegistry()
|
||||
|
||||
let store = try registry.acquire(fixture.root)
|
||||
defer { registry.release(store) }
|
||||
|
||||
await waitUntil { fixture.exists(AgentGuide.filename) }
|
||||
#expect(try fixture.data(AgentGuide.filename) == Data(AgentGuide.content.utf8))
|
||||
#expect(store.reloadFailure == nil)
|
||||
}
|
||||
|
||||
/// Self-healing, over the real FSEvents path: nothing in this test hands the store an event.
|
||||
@Test("A guide deleted under a live board comes back")
|
||||
func foreignDeletionHeals() async throws {
|
||||
let fixture = try makeBoard()
|
||||
defer { fixture.tearDown() }
|
||||
let registry = BoardStoreRegistry()
|
||||
|
||||
let store = try registry.acquire(fixture.root)
|
||||
defer { registry.release(store) }
|
||||
|
||||
await waitUntil { fixture.exists(AgentGuide.filename) }
|
||||
await settle()
|
||||
|
||||
try FileManager.default.removeItem(at: guideURL(in: fixture))
|
||||
#expect(!fixture.exists(AgentGuide.filename))
|
||||
|
||||
await waitUntil { fixture.exists(AgentGuide.filename) }
|
||||
#expect(try fixture.data(AgentGuide.filename) == Data(AgentGuide.content.utf8))
|
||||
#expect(store.reloadFailure == nil)
|
||||
}
|
||||
}
|
||||
@@ -23,9 +23,16 @@ import Testing
|
||||
// MARK: - Shared fixtures
|
||||
|
||||
/// A one-lane, one-card board, ready for whatever the test wants to leave beside `index.md`.
|
||||
///
|
||||
/// It carries a **current agent guide**, which is what any board the app has opened once looks like
|
||||
/// (08-agent-integration.md ▸ The agent guide). Without it the store's own guide refresh — which
|
||||
/// runs on every successful reload, beside this file's relocation — would write a `CLAUDE.md` on
|
||||
/// the first reload and open a bracket of its own, and the bracket counts below would stop being
|
||||
/// claims about the relocation.
|
||||
private func makeCardBoard() throws -> WriterFixture {
|
||||
let fixture = try WriterFixture()
|
||||
try fixture.item("", Item.board)
|
||||
try fixture.file(AgentGuide.filename, Data(AgentGuide.content.utf8))
|
||||
try fixture.item(Ident.lane1, Item.rich(order: "1024", title: "Todo"))
|
||||
try fixture.item("\(Ident.lane1)/\(Ident.card1)", Item.rich(order: "1024", title: "Fix login"))
|
||||
return fixture
|
||||
|
||||
Reference in New Issue
Block a user