bDS2/specs/git.allium

-- allium: 1
-- bDS Git Integration
-- Scope: extension (Bucket A — Git + Validation)
-- Distilled from: src/main/engine/GitEngine.ts

use "./post.allium" as post
use "./script.allium" as script
use "./template.allium" as template

value GitProvider {
    kind: github | gitlab | gitea_forgejo
    -- Detected from remote URL patterns
}

value GitSyncStatus {
    -- Per-commit: local_only | remote_only | both
    kind: local_only | remote_only | both
}

surface GitSyncStatusSurface {
    context status: GitSyncStatus

    exposes:
        status.kind
}

entity GitRepository {
    is_initialized: Boolean
    remote_url: String?
    provider: GitProvider?
    current_branch: String?
    has_lfs: Boolean
}

surface GitRepositorySurface {
    context repo: GitRepository

    exposes:
        repo.is_initialized
        repo.remote_url when repo.remote_url != null
        repo.provider when repo.provider != null
        repo.current_branch when repo.current_branch != null
        repo.has_lfs
}

surface GitControlSurface {
    facing _: GitOperator

    provides:
        InitializeRepoRequested(project)
        GitStatusRequested(project)
        GitDiffRequested(project)
        GitHistoryRequested(project, branch)
        GitFetchRequested(project)
        GitPullRequested(project)
        GitPushRequested(project)
        GitCommitAllRequested(project, message)
        GitReconcileRequested(project, old_commit, new_commit)
        PruneLfsCacheRequested(project, retain_recent)
}

rule InitializeRepo {
    when: InitializeRepoRequested(project)
    ensures: GitRepository.created(
        is_initialized: true,
        remote_url: null,
        provider: null,
        current_branch: "master",
        has_lfs: true
    )
    ensures: GitignoreCreated(project)
        -- .gitignore manages generated artifacts, cached assets, dependency directories, etc.
    ensures: LfsTrackingConfigured(project)
        -- Git LFS auto-tracks image patterns (*.jpg, *.png, *.gif, etc.)
}

rule GetStatus {
    when: GitStatusRequested(project)
    -- Returns file-level status: added, modified, deleted, renamed, untracked
    ensures: GitStatusReport(files)
}

rule GetDiff {
    when: GitDiffRequested(project)
    ensures: GitDiffReport(staged_diff, unstaged_diff)
}

rule GetHistory {
    when: GitHistoryRequested(project, branch)
    -- Returns commit history with sync status per commit
    ensures: GitHistoryReport(commits)
    @guidance
        -- Each commit annotated with: local_only, remote_only, or both
        -- This drives the "push needed" / "pull needed" indicators
}

rule Fetch {
    when: GitFetchRequested(project)
    ensures: RemoteRefsUpdated(project)
}

rule Pull {
    when: GitPullRequested(project)
    ensures: LocalBranchUpdated(project)
    ensures: GitReconcileRequested(project, previous_head(project), current_head(project))
        -- After pull, detect changed files and reconcile DB
}

rule Push {
    when: GitPushRequested(project)
    ensures: RemoteBranchUpdated(project)
}

rule CommitAll {
    when: GitCommitAllRequested(project, message)
    ensures: AllChangesStaged(project)
    ensures: CommitCreated(project, message)
}

-- Git reconciliation: sync DB from filesystem changes

rule ReconcileFromGit {
    when: GitReconcileRequested(project, old_commit, new_commit)
    -- Detect changed files between commits for posts, scripts, templates
    let post_changes = changed_post_files(old_commit, new_commit)
    let script_changes = changed_script_files(old_commit, new_commit)
    let template_changes = changed_template_files(old_commit, new_commit)

    for added in post_changes.added:
        ensures: post/Post.created(parse_post_file(added))
    for modified in post_changes.modified:
        ensures: PostUpdatedFromFile(modified)
    for deleted in post_changes.deleted:
        ensures: PostDeletedByPath(deleted)
    for renamed in post_changes.renamed:
        ensures: PostFileRenamed(renamed.old, renamed.new)

    -- Same pattern for scripts and templates
    for added in script_changes.added:
        ensures: script/Script.created(parse_script_file(added))
    for added in template_changes.added:
        ensures: template/Template.created(parse_template_file(added))

    ensures: EntityChangedEventsEmitted(project)
}

invariant NonInteractiveGit {
    -- All git operations run non-interactively:
    --   GIT_TERMINAL_PROMPT=0
    --   GCM_INTERACTIVE=never
    --   ssh -oBatchMode=yes
    -- No password prompts ever surface to the user
}

invariant StructuredAuthErrors {
    -- Auth failures produce structured guidance:
    --   per platform (macOS/Windows/Linux)
    --   per provider (GitHub/GitLab/Gitea)
    -- Instead of raw git error messages
}

rule PruneLfsCache {
    when: PruneLfsCacheRequested(project, retain_recent)
    -- Prunes LFS cache with configurable recent commit retention
    ensures: LfsCachePruned(project)
}