Add clone/pull progress callbacks and skill package

Author: linhay

.skills/dist/swift-git.skill

@@ -8,13 +8,15 @@ description: "Repository-focused skill for building, testing, and agent-safe ope
 Purpose
 - Provide concise, actionable instructions and examples for automated agents and humans working with this repository.
 - Expose the small set of repository-specific commands and agent rules an automated worker needs so the runtime can make safe decisions without loading large docs.
+- Include the progress-callback APIs for clone/pull so agents can guide UI work and cancellation behavior.
 
 When to use this skill (trigger examples)
 - "Build the package"
 - "Run tests"
 - "Run a single test"
 - "Where are the build/test commands"
 - "What agent rules should I follow for commits and CI"
+- "Add progress callbacks for clone or pull"
 
 Quick commands (do not execute without user approval)
 - Build (debug):
@@ -27,6 +29,28 @@ Quick commands (do not execute without user approval)
   - swift test --filter ParseTests.testChangedEntryIndex_valid
   - swift test --filter test_format_date
 
+Progress callbacks (clone/pull)
+- Types: `GitProgress`, `GitProgressStage`, `GitProgressAction` (Sources/SwiftGit/Custom/GitProgress.swift)
+- Clone overloads (Git):
+  - `clone(... progress: (GitProgress) -> Void)` for simple progress updates
+  - `clone(... progress: (GitProgress) -> GitProgressAction)` to allow cancellation (`.proceed` / `.cancel`)
+- Pull overloads (Repository):
+  - `pull(... progress: (GitProgress) -> Void)`
+  - `pull(... progress: (GitProgress) -> GitProgressAction)`
+- Callbacks are off-main; UI code should dispatch as needed.
+- Stage percent is per-stage and resets when stage changes.
+
+Example (cancel at 50% network)
+```swift
+let git = try Git(environment: .shared)
+_ = try await git.clone([.progress], repository: url, directory: "/tmp/repo") { progress in
+    if progress.stage == .network, (progress.stagePercent ?? 0) > 0.5 {
+        return .cancel
+    }
+    return .proceed
+}
+```
+
 Repository constraints (MUST follow)
 - Do NOT create commits or push to remote on behalf of a user unless explicitly authorized.
 - Do NOT modify the embedded git bundle at Sources/SwiftGit/Resource/git-instance.bundle.

.skills/swift-git/SKILL.md

@@ -61,6 +61,14 @@ Primary public types
   - public init(on event: Event, action: @escaping (_ result: Result<Content, Error>) -> Void)
   - public static func failure(on:event, action: ...) and success(on:event, action: ...)
 
+6) GitProgress / GitProgressStage / GitProgressAction (struct + enums)
+- Location: Sources/SwiftGit/Custom/GitProgress.swift
+- Summary: Progress snapshot types for long-running clone/pull operations, plus the action enum for cancellable callbacks.
+- Important public members:
+  - public struct GitProgress { receivedObjects, totalObjects, indexedObjects, receivedBytes, stage, stagePercent }
+  - public enum GitProgressStage { case network, indexing, checkout, done }
+  - public enum GitProgressAction { case proceed, cancel }
+
 Models (examples)
 - GitStatus (Sources/SwiftGit/Custom/models/GitStatus.swift): public struct GitStatus with properties branch, changed, renamedCopied, unmerged, untracked. Several nested types represent entries and styles.
 - Commit / Commit enums: Sources/SwiftGit/Custom/models/Commit.swift
@@ -73,6 +81,7 @@ Options
 
 Commands & repository extensions
 - Most git subcommands are exposed as public extensions on Git or Repository under Sources/SwiftGit/Custom/commands/*. Each file shapes a coherent sub-API (clone, commit, push, fetch, log, status, tag, stash, etc.).
+- Clone and pull now have progress callback overloads (see git-commands-clone.swift and git-commands-pull.swift).
 
 Tests that reference public APIs
 - Tests live under Tests/SwiftGitTests. Key files that exercise public APIs include:

.skills/swift-git/references/APIS.md

@@ -4,6 +4,7 @@ This section maps the command helper files in Sources/SwiftGit/Custom/commands/
 
 Files & purpose (selection)
 - git-commands-clone.swift — clone helpers and CloneOptions
+- git-commands-pull.swift — pull helpers and PullOptions (includes progress callbacks)
 - git-commands-commit.swift — commit helpers and CommitOptions
 - git-commands-status.swift — status helpers and StatusOptions
 - git-commands-log.swift — log helpers and LogOptions

.skills/swift-git/references/apis/Commands.md

@@ -6,6 +6,10 @@ GitStatus
 - Location: Sources/SwiftGit/Custom/models/GitStatus.swift
 - public struct GitStatus: Equatable with properties branch, changed, renamedCopied, unmerged, untracked and nested entry types.
 
+GitProgress
+- Location: Sources/SwiftGit/Custom/GitProgress.swift
+- public struct GitProgress with progress counters and stage; paired with GitProgressStage and GitProgressAction for clone/pull progress callbacks.
+
 Commit & User models
 - Sources/SwiftGit/Custom/models/Commit.swift
 - Sources/SwiftGit/Custom/results/LogResult.swift

.skills/swift-git/references/apis/Models.md

@@ -7,6 +7,7 @@ Public declaration highlights
 - public init(git: Git, url: URL)
 - public init(git: Git, path: String)
 - Many repository-scoped command helpers are defined as public extensions across Sources/SwiftGit/Custom/commands/*. These include clone, commit, push, status, tag, stash, fetch, pull, merge, etc.
+  - Pull includes progress callback overloads (GitProgress / GitProgressAction).
 
 Summary
 Repository is a lightweight wrapper that provides convenience methods executing git commands within a repository directory using an associated Git instance.

.skills/swift-git/references/apis/Repository.md

@@ -10,6 +10,7 @@
 - [GitEnvironment](symbols/GitEnvironment.md)（类） — Sources/SwiftGit/Custom/GitEnvironment.swift - Git 环境配置管理
 - [Shell](symbols/Shell.md)（工具） — Sources/SwiftGit/Custom/Shell.swift - 进程执行工具
 - [GitTrigger](symbols/GitTrigger.md)（结构体） — Sources/SwiftGit/Custom/GitTrigger.swift - 命令执行触发器
+- GitProgress / GitProgressStage / GitProgressAction（结构体/枚举） — Sources/SwiftGit/Custom/GitProgress.swift - 克隆/拉取进度回调类型与可取消动作
 
 ### 错误处理
 - [GitError](symbols/GitError.md)（枚举） — Sources/SwiftGit/Custom/GitError.swift - 统一的错误类型定义

.skills/swift-git/references/apis/zh/APIS.md

@@ -5,6 +5,7 @@
 
 文件与职责
 - git-commands-clone.swift — clone 相关 helper 与 CloneOptions
+- git-commands-pull.swift — pull helper 与 PullOptions（包含进度回调）
 - git-commands-commit.swift — commit helper 与 CommitOptions
 - git-commands-status.swift — status helper 与 StatusOptions
 - git-commands-log.swift — log helper 与 LogOptions

.skills/swift-git/references/apis/zh/Commands.md

@@ -6,6 +6,10 @@ GitStatus
 - 位置: Sources/SwiftGit/Custom/models/GitStatus.swift
 - 说明: `public struct GitStatus` 包含分支信息、已更改文件、重命名/拷贝、未合并、未跟踪项等。许多嵌套类型用于表示不同的条目。
 
+GitProgress
+- 位置: Sources/SwiftGit/Custom/GitProgress.swift
+- 说明: 进度快照类型，包含 receivedObjects/totalObjects/indexedObjects/receivedBytes 与 stage；配合 GitProgressStage 与 GitProgressAction 用于 clone/pull 进度回调与取消控制。
+
 Commit
 - 位置: Sources/SwiftGit/Custom/models/Commit.swift
 - 说明: 包含 Commit enum（如 HEAD、mnemonics 等）用于表示引用定位。

.skills/swift-git/references/apis/zh/Models.md

@@ -3,7 +3,8 @@
 位置: Sources/SwiftGit/Custom/Repository.swift
 
 概述
-- Repository 是对仓库目录里的 Git 操作的轻量封装，绑定在一个 Git 实例上，提供方便的方法来执行常见的 git 流程（commit、push、status、tag、stash 等）。
+- Repository 是对仓库目录里的 Git 操作的轻量封装，绑定在一个 Git 实例上，提供方便的方法来执行常见的 git 流程（commit、push、status、tag、stash、pull 等）。
+- pull 支持进度回调（GitProgress / GitProgressAction），适合 UI 展示与可取消操作。
 
 主要公开成员（节选）
 - public struct Repository