lanework/Kanban/Git/HistoryStore.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 is not part of it** — both tiers still bind
/// `NativeHistoryProvider` (`AppModel.makeHistoryProvider`), and the consumer of `mode` is the
/// undo/redo card two cards later, which builds the git `HistoryProviding` implementation over
/// exactly this object. Auto-commit, commit messages, branch controls, the identity fields, remotes
/// and `.gitignore` seeding are each their own card and deliberately absent here.
@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, or `nil` if the last attempt succeeded (or there hasn't been one).
    ///
    /// Surfaced inline in the popover rather than as a banner: the popover is where the operation
    /// was asked for and is still open when it answers, and 02-architecture.md's one-shot banner
    /// vocabulary is for failures of writes the user made *elsewhere*. DESIGN does not settle
    /// add-git's failure surface either way.
    public private(set) var lastFailure: GitOperationFailure?

    /// **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 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 no provider at all
    /// (`AppModel.makeHistoryProvider`), and 06 ▸ Rules ▸ Detection's one sanctioned commanded flip
    /// means the board now has a trail to be an undo stack over. What binding it 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)?

    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)
        }
    }

    /// **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()
    }

    /// Stops the committer — the session's teardown, so a closed board's debounce cannot fire against
    /// a store that has gone.
    public func stopAutoCommit() {
        committer?.stop()
    }

    /// **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 popover'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". 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 popover 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()
            // 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):
            lastFailure = 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. 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: - 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
    }
}