rzen
8345378972
The popover/sheet split lands: a board-scoped, titled, sectioned sheet on the board window hosts everything setup-shaped, opened from the popover's Board Settings… row and the new Board ▸ Board Settings… menu row. The three existing setup controls relocate — add-git (whose noteFormVisible lines now make the sheet the form-anchored failure surface), branch creation (a standing field; create-and-switch runs the identical settle sequence), and the commit-identity fields (the 2s visibility-scoped poll rides with them). The popover keeps the daily face and its postures; its Pro/mode-none section becomes header + door (.addGit renamed .noRepository). Availability is derived from the section inventory (Pro + mode none or git), so pro-m2's sections can't drift from the doors; the sheet's fields join the caret-chord disable set. The audit suite pins what the free fixture can reach; the sheet's own audit is manual until a tier override is ruled. Claude-Session: https://claude.ai/code/session_01CqjXB7ASoWtbyoGod68k97
401 lines
22 KiB
Swift
401 lines
22 KiB
Swift
import Foundation
|
|
import os
|
|
|
|
// MARK: - HistoryStore
|
|
|
|
/// **A board's git state** (02-architecture.md ▸ Components ▸ HistoryStore): which mode the board
|
|
/// opened in, the repository behind it when there is one, and the two operations that can change
|
|
/// either — the app's own add-git, and nothing else.
|
|
///
|
|
/// ### One per board session, composed under the tier
|
|
///
|
|
/// `compose(boardRoot:tier:)` is the whole gate: **the free tier gets no `HistoryStore` at all**, so
|
|
/// a free-tier session runs no detection, opens no repository, and does not so much as `stat` a
|
|
/// `.git` — "any `.git` is inert … the app never reads history, never commits, never touches `.git`
|
|
/// in any way" (12-editions.md ▸ The free tier and `.git`), which `InertGitTests` pins against real
|
|
/// bytes. Nothing in this type is conditional on a tier, because the tier decided whether the type
|
|
/// exists.
|
|
///
|
|
/// ### What it does not do yet
|
|
///
|
|
/// This is the foundation card of pro-m1: mode, a repository, add-git, and the loader's path-history
|
|
/// ranker. **The provider binding reads `mode` and nothing else about a tier** — the composition
|
|
/// root binds the git provider on mode `git` and the native stack on modes `none` and `repoNested`
|
|
/// alike (`AppModel.makeHistoryProvider`, re-ruled 2026-07-31: the provider follows the board, and
|
|
/// what a repo-nested board denies is app-managed history, never ⌘Z). Auto-commit, commit messages,
|
|
/// branch controls, the identity fields, the `.gitignore` seed and its periodic housekeeping each
|
|
/// arrived as their own card and are composed here now; remotes are pro-m2's and deliberately still
|
|
/// absent.
|
|
@MainActor
|
|
@Observable
|
|
public final class HistoryStore {
|
|
|
|
/// The board this is the git state of. The board root *is* the repository's working-tree root
|
|
/// in git mode — that is what mode `git` means.
|
|
public let boardRoot: URL
|
|
|
|
/// **Detected once, at composition, and changed by exactly one thing afterwards.**
|
|
///
|
|
/// "Detection is nearest-`.git`-wins, checked at every board open … never mid-session"
|
|
/// (06-history-undo.md ▸ Rules). A `git init` run in a terminal under an open board therefore
|
|
/// takes effect at its *next* open — the watcher does not scan for `.git` appearing, and nothing
|
|
/// re-runs `BoardGitMode.detect` for the life of this object.
|
|
///
|
|
/// The one deliberate mid-session transition is `addGit()` below: "the rule forbids *discovered*
|
|
/// flips, never commanded ones."
|
|
public private(set) var mode: BoardGitMode
|
|
|
|
/// The current branch's short name in git mode, `nil` until it has been read (or when there is
|
|
/// nothing to read).
|
|
///
|
|
/// Filled by `refreshBranch()` rather than at composition, deliberately: composition happens on
|
|
/// the board-open path, where 02-architecture.md's hang-avoidance doctrine says nothing may
|
|
/// block, and opening a repository is libgit2 work — small, but work. Detection is a `stat`;
|
|
/// this is a read, and it waits until the popover actually asks.
|
|
public private(set) var branch: String?
|
|
|
|
/// Whether add-git is in flight — the button's disabled state, and the guard that keeps a double
|
|
/// click from running `git_repository_init` twice.
|
|
public private(set) var isAddingGit = false
|
|
|
|
/// The last add-git failure while the form that asked is still on screen, or `nil`.
|
|
///
|
|
/// **Form-anchored operations answer at the form first** (06 ▸ Interaction with external writers,
|
|
/// ruled 2026-07-31): "add-git — and later sheet-asked operations like verify-remote — fail into
|
|
/// an inline caption in the sheet's relevant section while the sheet is up … if the sheet has been
|
|
/// dismissed before the answer arrives, the failure falls back to the one-shot banner above —
|
|
/// inline is the primary surface, never a silence trap."
|
|
///
|
|
/// So this property is exactly the *inline* half: it is set only while `isFormVisible`, and
|
|
/// dismissing the form clears it ("dismissing the sheet dismisses the stale error"). The other
|
|
/// half is `reportFailure`, which posts the banner when the answer arrives to an empty room.
|
|
///
|
|
/// The form is the **board settings sheet's Git section** (`BoardSettingsSheet`), which is where
|
|
/// the 2026-07-31 popover/sheet split put add-git; it was the popover's git section until that
|
|
/// sheet was built, and `noteFormVisible(_:)` is the one line the move re-pointed — the ruling's
|
|
/// container changed, its substance did not.
|
|
public private(set) var lastFailure: GitOperationFailure?
|
|
|
|
/// Whether the form add-git was asked from is on screen right now (`noteFormVisible(_:)`).
|
|
public private(set) var isFormVisible = false
|
|
|
|
/// **The auto-commit engine** (06-history-undo.md ▸ Rules ▸ Auto-commit), or `nil` on a board
|
|
/// there is no repository to commit into.
|
|
///
|
|
/// Its existence is exactly `mode == .git`, and that invariant is the tier gate one level down:
|
|
/// no `HistoryStore` off Pro means no committer anywhere off Pro, with nothing to disable and no
|
|
/// flag to forget.
|
|
///
|
|
/// **Composed inert and started separately.** Composition happens on the board-open path, where
|
|
/// nothing may block and where a session does not exist yet; `activateAutoCommit(_:)` is what
|
|
/// `AppModel.beginSession` calls once the store, the banner strip and the card windows are
|
|
/// reachable, and it is what arms the launch catch-up. A `HistoryStore` built without a session —
|
|
/// a test, a storeless consumer — therefore has a committer that never runs.
|
|
public private(set) var committer: GitAutoCommitter?
|
|
|
|
/// **The branch controls** (06-history-undo.md ▸ Branch switching), or `nil` on a board there is
|
|
/// no repository to switch branches in.
|
|
///
|
|
/// Its existence is exactly `mode == .git`, the committer's rule for the committer's reason — and
|
|
/// like the committer it is composed inert: the seams that make it a *sequence* (the settle step,
|
|
/// the store's bracket, the undo reseed, the banner strip) arrive from the session, and a
|
|
/// `HistoryStore` built without one has a switcher that can list branches and nothing else.
|
|
public private(set) var switcher: GitBranchSwitcher?
|
|
|
|
/// **Periodic safe housekeeping** (06-history-undo.md ▸ Repository hygiene), or `nil` on a board
|
|
/// there is no repository to maintain.
|
|
///
|
|
/// Its existence is exactly `mode == .git`, the committer's rule for the committer's reason, and
|
|
/// it is composed inert for a sharper version of the committer's: packing loose objects is the
|
|
/// most expensive thing this layer can do, and board open is where 02-architecture.md's
|
|
/// hang-avoidance doctrine is strictest. `activateAutoCommit(_:)` is what arms it — beside the
|
|
/// committer, so the two are one decision — and a `HistoryStore` built without a session has a
|
|
/// housekeeper that never runs.
|
|
public private(set) var housekeeper: GitHousekeeper?
|
|
|
|
// MARK: - Commit identity
|
|
|
|
/// **What repo-local `.git/config` says right now** — the settings sheet's two fields, as values
|
|
/// rather than as a resolved identity (06 ▸ Interaction with external writers: "The board settings
|
|
/// sheet's identity section … exposes name/email fields that write that repo-local config — the
|
|
/// setting *is* the file").
|
|
///
|
|
/// Empty means the file names no such key, which is what an empty field means: the derived default
|
|
/// applies, shown as the field's *placeholder*. Filling the field in with the derived value would
|
|
/// be the app writing its own guess into the user's repository the first time they edited anything
|
|
/// else on the sheet — the exact thing 06 rules out.
|
|
public private(set) var identityName = ""
|
|
|
|
public private(set) var identityEmail = ""
|
|
|
|
/// **The derived default**, for the placeholders — `nil` until `refreshIdentity()` has run.
|
|
///
|
|
/// Deliberately not computed at composition: `GitIdentity.derivedDefault()` reads
|
|
/// `ProcessInfo.hostName`, which can block on a machine whose name resolution is slow, and the
|
|
/// board-open path is where 02-architecture.md's hang-avoidance doctrine is strictest. It is read
|
|
/// off the main actor with the config, when the sheet asks.
|
|
public private(set) var derivedIdentity: GitIdentity?
|
|
|
|
/// The last identity-write failure, surfaced as an inline caption on the settings sheet beside the
|
|
/// fields — 06's form-anchored posture ("the user asked from a form still under their eye"), which
|
|
/// is exactly where `lastFailure` above already puts add-git's.
|
|
public private(set) var identityFailure: GitOperationFailure?
|
|
|
|
/// The board's write-provenance ledger, held so an add-git flip can build a committer over the
|
|
/// same one the session's store owns.
|
|
@ObservationIgnored
|
|
private let ledger: EchoLedger
|
|
|
|
/// How the session wires a committer up, remembered so the one built by a mid-session add-git
|
|
/// gets the same treatment as the one composed at open.
|
|
@ObservationIgnored
|
|
private var autoCommitWiring: ((GitAutoCommitter) -> Void)?
|
|
|
|
/// **The mid-session mode flip, announced** — called once, after a successful `addGit()`, and
|
|
/// never on any other path.
|
|
///
|
|
/// It exists because the flip has a second consumer beyond the committer: the board's **undo
|
|
/// substrate**. A session that composed on a mode-none board bound the native stack
|
|
/// (`AppModel.makeHistoryProvider`), and 06 ▸ Rules ▸ Detection's one sanctioned commanded flip
|
|
/// means the board now has a trail to be an undo stack over instead — "add-git swaps the
|
|
/// substrate mid-session … discards the in-session native stack and seeds the git trail from the
|
|
/// root commit" (13-native-undo.md). What that swap means is
|
|
/// `AppModel.bindHistoryProvider(for:)`'s to decide and to justify; what this property does is
|
|
/// keep that decision out of a git state that has no business knowing what a provider is.
|
|
@ObservationIgnored
|
|
public var didAddGit: (@MainActor () -> Void)?
|
|
|
|
/// **The banner half of the form-anchored posture** — where a form-asked failure goes when the
|
|
/// form is gone (`BannerCenter.postGitFailure`). `nil` on a storeless `HistoryStore`, which has no
|
|
/// strip to post to; the inline half still works there.
|
|
@ObservationIgnored
|
|
public var reportFailure: (@MainActor (GitOperationFailure) -> Void)?
|
|
|
|
/// **The form appeared or was dismissed.** Dismissal clears the stale inline error, which is the
|
|
/// ruling's own sentence ("dismissing the sheet dismisses the stale error, retry is right there").
|
|
///
|
|
/// A `Bool` rather than a count because there is one such form per board at a time: the settings
|
|
/// sheet is modal to its board window, and opening it dismisses the popover.
|
|
public func noteFormVisible(_ visible: Bool) {
|
|
isFormVisible = visible
|
|
if !visible { lastFailure = nil }
|
|
}
|
|
|
|
private static let logger = Logger(subsystem: "dev.rzen.indie.Kanban", category: "git")
|
|
|
|
init(boardRoot: URL, mode: BoardGitMode, ledger: EchoLedger) {
|
|
self.boardRoot = boardRoot
|
|
self.mode = mode
|
|
self.ledger = ledger
|
|
if mode == .git {
|
|
committer = GitAutoCommitter(boardRoot: boardRoot, ledger: ledger)
|
|
switcher = GitBranchSwitcher(boardRoot: boardRoot)
|
|
housekeeper = GitHousekeeper(boardRoot: boardRoot)
|
|
}
|
|
}
|
|
|
|
/// **Wires the committer into its session and starts it** — `AppModel.beginSession`'s call.
|
|
///
|
|
/// Separate from composition for two reasons that point the same way: the seams a committer needs
|
|
/// (the banner strip, the board's snapshot, the card windows' Edit sessions) belong to a session
|
|
/// that does not exist when `compose` runs, and arming a debounce is a side effect no *detection*
|
|
/// should have. The wiring is remembered because add-git can produce a committer later, and a
|
|
/// board that flipped into git mode mid-session must commit exactly like one that opened in it.
|
|
public func activateAutoCommit(_ wire: @escaping (GitAutoCommitter) -> Void) {
|
|
autoCommitWiring = wire
|
|
guard let committer else { return }
|
|
wire(committer)
|
|
committer.start()
|
|
armHousekeeping(beside: committer)
|
|
}
|
|
|
|
/// Stops the committer, and the maintenance beside it — the session's teardown, so neither a
|
|
/// closed board's debounce nor its housekeeping can fire against a store that has gone.
|
|
public func stopAutoCommit() {
|
|
committer?.stop()
|
|
housekeeper?.cancel()
|
|
}
|
|
|
|
/// **Arms the board-open housekeeping pass** (06 ▸ Repository hygiene) — one call site's worth of
|
|
/// wiring, shared by the session's activation and by a mid-session add-git, so a board that
|
|
/// flipped into git mode maintains itself exactly like one that opened in it.
|
|
///
|
|
/// The gate it hands over is the committer's own in-flight flag, read at the moment of dispatch:
|
|
/// the simplest honest way to keep optional work from starting beside the one operation that must
|
|
/// never be disturbed, and deliberately not a lock — see `GitHousekeeper.runNow()`.
|
|
private func armHousekeeping(beside committer: GitAutoCommitter) {
|
|
guard let housekeeper else { return }
|
|
housekeeper.isCommitInFlight = { [weak committer] in committer?.isCommitInFlight ?? false }
|
|
housekeeper.schedule()
|
|
}
|
|
|
|
/// **The tier gate and the open-time detection, in one line** (12-editions.md ▸ The provider
|
|
/// seam; 06-history-undo.md ▸ Rules ▸ Detection) — called by `AppModel.beginSession` beside the
|
|
/// entitlement read that supplies `tier`.
|
|
///
|
|
/// `nil` under `.free` means exactly what it says: no git state exists for that session, so no
|
|
/// caller can accidentally consult one. Under `.pro` the mode is whatever the filesystem says
|
|
/// right now, and a board that has changed mode since its last open simply opens in the new one
|
|
/// — "the app just reflects what it finds".
|
|
///
|
|
/// **Adoption needs no step of its own**: a board whose root already carries `.git` lands in
|
|
/// `.git` here, silently, with no dialog and nothing to confirm — "the repo's presence *is* the
|
|
/// opt-in" (06 ▸ Rules ▸ Adoption).
|
|
///
|
|
/// - Parameter ledger: the board's write-provenance ledger (`BoardStore.echoes`) — what the
|
|
/// auto-committer classifies each changed file against. Defaulted to a fresh one so a
|
|
/// store-less `HistoryStore` still composes: an empty ledger vouches for nothing, which is the
|
|
/// honest answer for a git state with no session behind it (everything reads foreign, the
|
|
/// launch-catch-up doctrine).
|
|
public static func compose(boardRoot: URL, tier: Tier, ledger: EchoLedger = EchoLedger()) -> HistoryStore? {
|
|
guard tier == .pro else { return nil }
|
|
let mode = BoardGitMode.detect(boardRoot: boardRoot)
|
|
logger.debug("board opened in git mode \(mode.rawValue, privacy: .public)")
|
|
return HistoryStore(boardRoot: boardRoot, mode: mode, ledger: ledger)
|
|
}
|
|
|
|
// MARK: - Add git
|
|
|
|
/// **Opt-in init** (06-history-undo.md ▸ Rules): initializes a repository at the board root and
|
|
/// immediately commits the whole tree as "Initial board state".
|
|
///
|
|
/// Reachable from one place — the board settings sheet's Git section under Pro — and from nowhere
|
|
/// else:
|
|
/// "No silent auto-init, ever", a deliberate pivot from the pathfinder, which initialized a repo
|
|
/// under every board it opened.
|
|
///
|
|
/// **It flips the open board's mode immediately**, which is the design's one sanctioned
|
|
/// mid-session transition: "clicking it flips the open board into git mode immediately — the
|
|
/// popover flows straight into the git controls". Since the 2026-07-31 split that flow is one
|
|
/// surface further along — the sheet's Git section becomes its Branch and Commit Identity
|
|
/// sections, and the popover behind it gains the branch line — but the immediacy is the same. The
|
|
/// flip is commanded, not discovered, which is what distinguishes it from the `git init` a user
|
|
/// runs in a terminal under an open board.
|
|
///
|
|
/// Only mode `none` can be added to. Mode `git` has nothing to add, and a repo-nested board is
|
|
/// one the app "leaves strictly alone" — no nested repo, ever.
|
|
@discardableResult
|
|
public func addGit() async -> Bool {
|
|
guard mode == .none, !isAddingGit else { return false }
|
|
|
|
isAddingGit = true
|
|
lastFailure = nil
|
|
defer { isAddingGit = false }
|
|
|
|
let root = boardRoot
|
|
// Off the main actor: `git_repository_init` plus a whole-tree stage and commit is real
|
|
// filesystem work, and the sheet it was clicked in stays live while it runs.
|
|
let outcome = await Task.detached(priority: .userInitiated) {
|
|
GitRepository.create(at: root)
|
|
}.value
|
|
|
|
switch outcome {
|
|
case .success(let branchName):
|
|
mode = .git
|
|
branch = branchName
|
|
// **The commanded mid-session flip, carried through to the engine** (06 ▸ Rules ▸
|
|
// Detection: "clicking it flips the open board into git mode immediately — the popover
|
|
// flows straight into the git controls, the first auto-commit follows"). The root commit
|
|
// has already landed inside `create`, so what `start()` arms here finds a clean tree and
|
|
// no-ops; what it buys is that the *next* settled change commits, exactly as on a board
|
|
// that opened in git mode.
|
|
let committer = GitAutoCommitter(boardRoot: root, ledger: ledger)
|
|
self.committer = committer
|
|
autoCommitWiring?(committer)
|
|
committer.start()
|
|
// The branch controls appear with the repository they switch branches in — and before
|
|
// `didAddGit`, which is what wires their seams (`AppModel.wireGitUndo`).
|
|
switcher = GitBranchSwitcher(boardRoot: root)
|
|
// Housekeeping too, for the committer's reason: a board that flipped mid-session behaves
|
|
// like one that opened in git mode. A repository seconds old has a handful of loose
|
|
// objects and will read below threshold — which is the pass doing its job, not skipping.
|
|
housekeeper = GitHousekeeper(boardRoot: root)
|
|
armHousekeeping(beside: committer)
|
|
// Last, after the mode and the committer: the undo binding reads both.
|
|
didAddGit?()
|
|
Self.logger.notice("add-git initialized a repository at \(root.path, privacy: .public)")
|
|
return true
|
|
case .failure(let failure):
|
|
// **Inline while the form is up, the banner when it is not** (06, ruled 2026-07-31) — the
|
|
// answer can outlive the surface that asked for it, and a failure with nowhere to land
|
|
// would be the silence trap the ruling names.
|
|
if isFormVisible {
|
|
lastFailure = failure
|
|
} else {
|
|
lastFailure = nil
|
|
reportFailure?(failure)
|
|
}
|
|
Self.logger.error("add-git failed: \(failure.description, privacy: .public)")
|
|
return false
|
|
}
|
|
}
|
|
|
|
/// Reads the current branch name into `branch` — the popover's read-only display line, refreshed
|
|
/// when the popover opens (and when the settings sheet does, whose create control reads the same
|
|
/// surface). A no-op outside git mode.
|
|
public func refreshBranch() async {
|
|
guard mode == .git else { return }
|
|
let root = boardRoot
|
|
branch = await Task.detached(priority: .userInitiated) {
|
|
GitRepository.branchName(at: root)
|
|
}.value
|
|
}
|
|
|
|
// MARK: - Commit identity
|
|
|
|
/// Reads repo-local config and the derived default into the settings sheet's fields. A no-op
|
|
/// outside git mode, `refreshBranch()`'s rule.
|
|
///
|
|
/// Both reads run off the main actor: one opens a repository, the other asks the system for the
|
|
/// account and host names.
|
|
public func refreshIdentity() async {
|
|
guard mode == .git else { return }
|
|
let root = boardRoot
|
|
let read = await Task.detached(priority: .userInitiated) {
|
|
(
|
|
repoLocal: GitCommitOperation.repoLocalIdentity(at: root),
|
|
derived: GitIdentity.derivedDefault()
|
|
)
|
|
}.value
|
|
identityName = read.repoLocal.name ?? ""
|
|
identityEmail = read.repoLocal.email ?? ""
|
|
derivedIdentity = read.derived
|
|
}
|
|
|
|
/// **Writes the fields into repo-local `.git/config`** — "the setting *is* the file".
|
|
///
|
|
/// An empty value clears its key rather than writing an empty string, which is what the
|
|
/// placeholder promises: an empty field means the derived default applies. The read afterwards is
|
|
/// not ceremony — it is how the fields end up showing what the file says rather than what was
|
|
/// typed at it, which is the only version that survives a foreign edit landing in between.
|
|
public func writeIdentity(name: String, email: String) async {
|
|
guard mode == .git else { return }
|
|
let root = boardRoot
|
|
identityFailure = nil
|
|
let outcome = await Task.detached(priority: .userInitiated) {
|
|
GitCommitOperation.writeRepoLocalIdentity(name: name, email: email, at: root)
|
|
}.value
|
|
if case let .failure(failure) = outcome {
|
|
identityFailure = failure
|
|
Self.logger.error("identity write failed: \(failure.description, privacy: .public)")
|
|
}
|
|
await refreshIdentity()
|
|
}
|
|
|
|
// MARK: - The loader's history seam
|
|
|
|
/// **The git-backed `IdentityHistoryRanker`** (01-storage-format.md ▸ Fractal layout ▸ Rules;
|
|
/// `BoardLoader.IdentityHistoryRanker`), or `nil` on any board the app manages no git for — the
|
|
/// free tier and modes `none`/`repoNested` alike, all of which fall through to the ladder's
|
|
/// remaining rungs (birth date, then traversal order).
|
|
///
|
|
/// **A fresh ranker per ask, deliberately.** Each one computes its map at most once, lazily, and
|
|
/// only if something actually asks — which is only when a duplicate identity was found, since
|
|
/// that is the only thing `BoardLoader.dedupeIdentities` consults it for. A ranker cached across
|
|
/// loads would answer from a history that has since moved; one built per load never can.
|
|
public var identityHistoryRanker: BoardLoader.IdentityHistoryRanker? {
|
|
guard mode == .git else { return nil }
|
|
return GitPathHistory(boardRoot: boardRoot).ranker
|
|
}
|
|
}
|