agentskills-git 0.8.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agentskills-git
|
|
3
|
+
Version: 0.8.0
|
|
4
|
+
Summary: Git-backed provider for reproducible Agent Skills sources (https://agentskills.io)
|
|
5
|
+
License: MIT
|
|
6
|
+
Author: Pratik Panda
|
|
7
|
+
Requires-Python: >=3.12,<4.0
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
16
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
17
|
+
Requires-Dist: agentskills-core (>=0.8.0,<1.0)
|
|
18
|
+
Requires-Dist: agentskills-fs (>=0.8.0,<1.0)
|
|
19
|
+
Project-URL: Homepage, https://agentskills.io
|
|
20
|
+
Project-URL: Repository, https://github.com/pratikxpanda/agentskills-sdk
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
title: agentskills-git
|
|
25
|
+
description: Read Agent Skills from Git repositories at immutable commits.
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
[](https://pypi.org/project/agentskills-git/)
|
|
29
|
+
[](https://github.com/pratikxpanda/agentskills-sdk/blob/main/LICENSE)
|
|
30
|
+
|
|
31
|
+
Read Agent Skills from a Git repository at a ref resolved to an immutable commit. The provider
|
|
32
|
+
uses Git and delegates skill reads to `agentskills-fs`.
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pip install agentskills-git
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Python 3.12 or newer and the Git command-line executable must be available on `PATH`.
|
|
41
|
+
The configured repository must already contain valid skill directories. Set `subdirectory`
|
|
42
|
+
when they are beneath a folder such as `skills/` rather than the repository root.
|
|
43
|
+
|
|
44
|
+
## Usage
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
import asyncio
|
|
48
|
+
from pathlib import Path
|
|
49
|
+
|
|
50
|
+
from agentskills_core import SkillRegistry, capture_skill
|
|
51
|
+
from agentskills_git import GitSkillProvider
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
async def main() -> None:
|
|
55
|
+
provider = GitSkillProvider(
|
|
56
|
+
"https://github.com/example/skills.git",
|
|
57
|
+
"main",
|
|
58
|
+
Path(".cache/agent-skills"),
|
|
59
|
+
subdirectory="skills",
|
|
60
|
+
)
|
|
61
|
+
registry = SkillRegistry()
|
|
62
|
+
await registry.register_all(provider)
|
|
63
|
+
print(provider.resolved_commit)
|
|
64
|
+
|
|
65
|
+
snapshot = await capture_skill(registry.get_skill("incident-response"))
|
|
66
|
+
for file in snapshot.files:
|
|
67
|
+
print(file.path, file.digest)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
asyncio.run(main())
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Replace the repository URL, ref, and skill ID with your source. The directory layout matches
|
|
74
|
+
the [filesystem provider](https://github.com/pratikxpanda/agentskills-sdk/blob/main/packages/providers/agentskills-fs/README.md#expected-directory-layout).
|
|
75
|
+
A branch or tag is resolved on first access. That provider instance continues to use the same
|
|
76
|
+
commit even when the remote ref moves. Construct a new provider with `refresh=True` to fetch
|
|
77
|
+
the ref again. The provider holds a cache lease for its lifetime and releases it through its
|
|
78
|
+
finalizer. There is no public `close` or `aclose` method.
|
|
79
|
+
|
|
80
|
+
## Security and limits
|
|
81
|
+
|
|
82
|
+
The provider does not run repository hooks, submodules, or skill scripts. It ignores system and global
|
|
83
|
+
Git configuration and disables the `ext` transport. Symlink entries are rejected. The cache has a
|
|
84
|
+
configurable size limit per checkout (`max_cache_bytes`, 256 MiB by default) and a 1 GiB total
|
|
85
|
+
limit (`max_total_cache_bytes`). Least-recently-used inactive checkouts are evicted to stay within
|
|
86
|
+
the total limit. File locks protect active checkouts across processes. Remote authentication uses Git's supported transport
|
|
87
|
+
mechanisms, except credentials from global Git configuration are not loaded by this provider.
|
|
88
|
+
|
|
89
|
+
Broader Git host compatibility is still being tested.
|
|
90
|
+
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: agentskills-git
|
|
3
|
+
description: Read Agent Skills from Git repositories at immutable commits.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
[](https://pypi.org/project/agentskills-git/)
|
|
7
|
+
[](https://github.com/pratikxpanda/agentskills-sdk/blob/main/LICENSE)
|
|
8
|
+
|
|
9
|
+
Read Agent Skills from a Git repository at a ref resolved to an immutable commit. The provider
|
|
10
|
+
uses Git and delegates skill reads to `agentskills-fs`.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
pip install agentskills-git
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Python 3.12 or newer and the Git command-line executable must be available on `PATH`.
|
|
19
|
+
The configured repository must already contain valid skill directories. Set `subdirectory`
|
|
20
|
+
when they are beneath a folder such as `skills/` rather than the repository root.
|
|
21
|
+
|
|
22
|
+
## Usage
|
|
23
|
+
|
|
24
|
+
```python
|
|
25
|
+
import asyncio
|
|
26
|
+
from pathlib import Path
|
|
27
|
+
|
|
28
|
+
from agentskills_core import SkillRegistry, capture_skill
|
|
29
|
+
from agentskills_git import GitSkillProvider
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
async def main() -> None:
|
|
33
|
+
provider = GitSkillProvider(
|
|
34
|
+
"https://github.com/example/skills.git",
|
|
35
|
+
"main",
|
|
36
|
+
Path(".cache/agent-skills"),
|
|
37
|
+
subdirectory="skills",
|
|
38
|
+
)
|
|
39
|
+
registry = SkillRegistry()
|
|
40
|
+
await registry.register_all(provider)
|
|
41
|
+
print(provider.resolved_commit)
|
|
42
|
+
|
|
43
|
+
snapshot = await capture_skill(registry.get_skill("incident-response"))
|
|
44
|
+
for file in snapshot.files:
|
|
45
|
+
print(file.path, file.digest)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
asyncio.run(main())
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Replace the repository URL, ref, and skill ID with your source. The directory layout matches
|
|
52
|
+
the [filesystem provider](https://github.com/pratikxpanda/agentskills-sdk/blob/main/packages/providers/agentskills-fs/README.md#expected-directory-layout).
|
|
53
|
+
A branch or tag is resolved on first access. That provider instance continues to use the same
|
|
54
|
+
commit even when the remote ref moves. Construct a new provider with `refresh=True` to fetch
|
|
55
|
+
the ref again. The provider holds a cache lease for its lifetime and releases it through its
|
|
56
|
+
finalizer. There is no public `close` or `aclose` method.
|
|
57
|
+
|
|
58
|
+
## Security and limits
|
|
59
|
+
|
|
60
|
+
The provider does not run repository hooks, submodules, or skill scripts. It ignores system and global
|
|
61
|
+
Git configuration and disables the `ext` transport. Symlink entries are rejected. The cache has a
|
|
62
|
+
configurable size limit per checkout (`max_cache_bytes`, 256 MiB by default) and a 1 GiB total
|
|
63
|
+
limit (`max_total_cache_bytes`). Least-recently-used inactive checkouts are evicted to stay within
|
|
64
|
+
the total limit. File locks protect active checkouts across processes. Remote authentication uses Git's supported transport
|
|
65
|
+
mechanisms, except credentials from global Git configuration are not loaded by this provider.
|
|
66
|
+
|
|
67
|
+
Broader Git host compatibility is still being tested.
|
|
@@ -0,0 +1,508 @@
|
|
|
1
|
+
"""Serve Agent Skills from a Git revision pinned to its resolved commit."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import contextlib
|
|
7
|
+
import errno
|
|
8
|
+
import hashlib
|
|
9
|
+
import importlib
|
|
10
|
+
import os
|
|
11
|
+
import re
|
|
12
|
+
import shutil
|
|
13
|
+
import stat
|
|
14
|
+
import subprocess
|
|
15
|
+
import tempfile
|
|
16
|
+
import threading
|
|
17
|
+
import time
|
|
18
|
+
import uuid
|
|
19
|
+
import weakref
|
|
20
|
+
from pathlib import Path, PurePosixPath
|
|
21
|
+
from typing import Any
|
|
22
|
+
|
|
23
|
+
from agentskills_core import SkillProvider
|
|
24
|
+
from agentskills_fs import LocalFileSystemSkillProvider
|
|
25
|
+
|
|
26
|
+
DEFAULT_MAX_CACHE_BYTES = 256 * 1024 * 1024
|
|
27
|
+
DEFAULT_MAX_TOTAL_CACHE_BYTES = 1024 * 1024 * 1024
|
|
28
|
+
_COMMIT_PATTERN = re.compile(r"[0-9a-f]{40,64}")
|
|
29
|
+
_CACHE_LOCK = threading.RLock()
|
|
30
|
+
_ACTIVE_PROVIDERS: weakref.WeakSet = weakref.WeakSet()
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _ensure_lock_byte(stream: Any) -> None:
|
|
34
|
+
stream.seek(0, os.SEEK_END)
|
|
35
|
+
if stream.tell() == 0:
|
|
36
|
+
stream.write(b"\0")
|
|
37
|
+
stream.flush()
|
|
38
|
+
stream.seek(0)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _is_windows() -> bool:
|
|
42
|
+
return os.name == "nt"
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _lock_file(stream: Any, *, blocking: bool) -> None:
|
|
46
|
+
_ensure_lock_byte(stream)
|
|
47
|
+
if _is_windows():
|
|
48
|
+
lock_api = importlib.import_module("msvcrt")
|
|
49
|
+
if not blocking:
|
|
50
|
+
lock_api.locking(stream.fileno(), lock_api.LK_NBLCK, 1)
|
|
51
|
+
return
|
|
52
|
+
deadline = time.monotonic() + 300
|
|
53
|
+
while True:
|
|
54
|
+
stream.seek(0)
|
|
55
|
+
try:
|
|
56
|
+
lock_api.locking(stream.fileno(), lock_api.LK_NBLCK, 1)
|
|
57
|
+
return
|
|
58
|
+
except OSError as exc:
|
|
59
|
+
if exc.errno not in {errno.EACCES, errno.EDEADLK} and getattr(
|
|
60
|
+
exc, "winerror", None
|
|
61
|
+
) not in {32, 33}:
|
|
62
|
+
raise
|
|
63
|
+
if time.monotonic() >= deadline:
|
|
64
|
+
raise
|
|
65
|
+
time.sleep(0.05)
|
|
66
|
+
else:
|
|
67
|
+
lock_api = importlib.import_module("fcntl")
|
|
68
|
+
mode = lock_api.LOCK_EX | (0 if blocking else lock_api.LOCK_NB)
|
|
69
|
+
lock_api.flock(stream.fileno(), mode)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _unlock_file(stream: Any) -> None:
|
|
73
|
+
stream.seek(0)
|
|
74
|
+
if _is_windows():
|
|
75
|
+
lock_api = importlib.import_module("msvcrt")
|
|
76
|
+
lock_api.locking(stream.fileno(), lock_api.LK_UNLCK, 1)
|
|
77
|
+
else:
|
|
78
|
+
lock_api = importlib.import_module("fcntl")
|
|
79
|
+
lock_api.flock(stream.fileno(), lock_api.LOCK_UN)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
@contextlib.contextmanager
|
|
83
|
+
def _cache_directory_lock(cache_dir: Path):
|
|
84
|
+
with (cache_dir / ".agentskills-cache.lock").open("a+b") as stream:
|
|
85
|
+
_lock_file(stream, blocking=True)
|
|
86
|
+
try:
|
|
87
|
+
yield
|
|
88
|
+
finally:
|
|
89
|
+
_unlock_file(stream)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _release_cache_lease(stream: Any, path: Path) -> None:
|
|
93
|
+
with contextlib.suppress(OSError):
|
|
94
|
+
_unlock_file(stream)
|
|
95
|
+
stream.close()
|
|
96
|
+
path.unlink(missing_ok=True)
|
|
97
|
+
with contextlib.suppress(OSError):
|
|
98
|
+
path.parent.rmdir()
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
class GitSkillProviderError(RuntimeError):
|
|
102
|
+
"""Raised when a repository revision cannot be resolved or cached."""
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
class GitSkillProvider(SkillProvider):
|
|
106
|
+
"""Read skills from a Git repository at one immutable resolved commit.
|
|
107
|
+
|
|
108
|
+
The configured ref is resolved on first access. The resulting commit is
|
|
109
|
+
cached and exposed through :attr:`resolved_commit`; later reads use that
|
|
110
|
+
checkout even if the remote ref moves. The selected directory must contain
|
|
111
|
+
skill directories directly beneath it, matching the filesystem provider.
|
|
112
|
+
|
|
113
|
+
Git hooks, system and global Git configuration, submodules, and external
|
|
114
|
+
Git protocols are disabled for the fetch. Skill scripts are never run.
|
|
115
|
+
|
|
116
|
+
Args:
|
|
117
|
+
repository: Git URL or local repository path.
|
|
118
|
+
ref: Branch, tag, or commit reference to resolve on first access.
|
|
119
|
+
cache_dir: Directory for the pinned checkout.
|
|
120
|
+
subdirectory: POSIX repository-relative directory containing skills.
|
|
121
|
+
max_cache_bytes: Maximum size of the checkout and Git metadata.
|
|
122
|
+
max_total_cache_bytes: Maximum total size of completed checkouts in the cache.
|
|
123
|
+
|
|
124
|
+
Raises:
|
|
125
|
+
ValueError: If the ref, subdirectory, or cache limit is invalid.
|
|
126
|
+
|
|
127
|
+
Example:
|
|
128
|
+
>>> provider = GitSkillProvider(
|
|
129
|
+
... "https://github.com/example/skills.git", "main", Path(".cache/skills")
|
|
130
|
+
... )
|
|
131
|
+
>>> skills = await provider.discover()
|
|
132
|
+
"""
|
|
133
|
+
|
|
134
|
+
supports_resource_listing = True
|
|
135
|
+
supports_discovery = True
|
|
136
|
+
supports_file_access = True
|
|
137
|
+
|
|
138
|
+
def __init__(
|
|
139
|
+
self,
|
|
140
|
+
repository: str,
|
|
141
|
+
ref: str,
|
|
142
|
+
cache_dir: Path,
|
|
143
|
+
*,
|
|
144
|
+
subdirectory: str = ".",
|
|
145
|
+
max_cache_bytes: int = DEFAULT_MAX_CACHE_BYTES,
|
|
146
|
+
max_total_cache_bytes: int = DEFAULT_MAX_TOTAL_CACHE_BYTES,
|
|
147
|
+
refresh: bool = False,
|
|
148
|
+
) -> None:
|
|
149
|
+
if not repository:
|
|
150
|
+
raise ValueError("repository must not be empty")
|
|
151
|
+
if not ref or ref.startswith("-") or "\x00" in ref:
|
|
152
|
+
raise ValueError("ref must be a non-empty Git reference")
|
|
153
|
+
if "\\" in subdirectory or "\x00" in subdirectory:
|
|
154
|
+
raise ValueError("subdirectory must be a POSIX relative path")
|
|
155
|
+
relative = PurePosixPath(subdirectory)
|
|
156
|
+
if relative.is_absolute() or ".." in relative.parts:
|
|
157
|
+
raise ValueError("subdirectory must stay within the repository")
|
|
158
|
+
if max_cache_bytes < 0:
|
|
159
|
+
raise ValueError("max_cache_bytes must be non-negative")
|
|
160
|
+
if max_total_cache_bytes < 0:
|
|
161
|
+
raise ValueError("max_total_cache_bytes must be non-negative")
|
|
162
|
+
|
|
163
|
+
self.repository = repository
|
|
164
|
+
self.ref = ref
|
|
165
|
+
self.cache_dir = Path(cache_dir)
|
|
166
|
+
self.subdirectory = relative
|
|
167
|
+
self.max_cache_bytes = max_cache_bytes
|
|
168
|
+
self.max_total_cache_bytes = max_total_cache_bytes
|
|
169
|
+
self._lock = threading.Lock()
|
|
170
|
+
self._provider: LocalFileSystemSkillProvider | None = None
|
|
171
|
+
self._resolved_commit: str | None = None
|
|
172
|
+
self._lease_finalizer: weakref.finalize | None = None
|
|
173
|
+
identity = "\0".join((repository, ref, relative.as_posix()))
|
|
174
|
+
if refresh:
|
|
175
|
+
identity += "\0refresh\0" + uuid.uuid4().hex
|
|
176
|
+
self._cache_path = self.cache_dir / hashlib.sha256(identity.encode()).hexdigest()
|
|
177
|
+
|
|
178
|
+
@property
|
|
179
|
+
def resolved_commit(self) -> str | None:
|
|
180
|
+
"""Commit SHA resolved on first access, or ``None`` before access."""
|
|
181
|
+
return self._resolved_commit
|
|
182
|
+
|
|
183
|
+
async def get_metadata(self, skill_id: str) -> dict[str, Any]:
|
|
184
|
+
"""Return parsed frontmatter for a skill.
|
|
185
|
+
|
|
186
|
+
Args:
|
|
187
|
+
skill_id: Skill identifier.
|
|
188
|
+
|
|
189
|
+
Returns:
|
|
190
|
+
Parsed frontmatter metadata.
|
|
191
|
+
"""
|
|
192
|
+
return await (await self._get_provider()).get_metadata(skill_id)
|
|
193
|
+
|
|
194
|
+
async def get_body(self, skill_id: str) -> str:
|
|
195
|
+
"""Return the instruction body for a skill.
|
|
196
|
+
|
|
197
|
+
Args:
|
|
198
|
+
skill_id: Skill identifier.
|
|
199
|
+
|
|
200
|
+
Returns:
|
|
201
|
+
Markdown instruction body.
|
|
202
|
+
"""
|
|
203
|
+
return await (await self._get_provider()).get_body(skill_id)
|
|
204
|
+
|
|
205
|
+
async def get_script(self, skill_id: str, name: str) -> bytes:
|
|
206
|
+
"""Return a script file without executing it.
|
|
207
|
+
|
|
208
|
+
Args:
|
|
209
|
+
skill_id: Skill identifier.
|
|
210
|
+
name: Script filename.
|
|
211
|
+
|
|
212
|
+
Returns:
|
|
213
|
+
Original script bytes.
|
|
214
|
+
"""
|
|
215
|
+
return await (await self._get_provider()).get_script(skill_id, name)
|
|
216
|
+
|
|
217
|
+
async def get_asset(self, skill_id: str, name: str) -> bytes:
|
|
218
|
+
"""Return an asset file as bytes.
|
|
219
|
+
|
|
220
|
+
Args:
|
|
221
|
+
skill_id: Skill identifier.
|
|
222
|
+
name: Asset filename.
|
|
223
|
+
|
|
224
|
+
Returns:
|
|
225
|
+
Original asset bytes.
|
|
226
|
+
"""
|
|
227
|
+
return await (await self._get_provider()).get_asset(skill_id, name)
|
|
228
|
+
|
|
229
|
+
async def get_reference(self, skill_id: str, name: str) -> bytes:
|
|
230
|
+
"""Return a reference file as bytes.
|
|
231
|
+
|
|
232
|
+
Args:
|
|
233
|
+
skill_id: Skill identifier.
|
|
234
|
+
name: Reference filename.
|
|
235
|
+
|
|
236
|
+
Returns:
|
|
237
|
+
Original reference bytes.
|
|
238
|
+
"""
|
|
239
|
+
return await (await self._get_provider()).get_reference(skill_id, name)
|
|
240
|
+
|
|
241
|
+
async def list_resources(self, skill_id: str) -> dict[str, list[str]]:
|
|
242
|
+
"""List standard resource files for a skill.
|
|
243
|
+
|
|
244
|
+
Args:
|
|
245
|
+
skill_id: Skill identifier.
|
|
246
|
+
|
|
247
|
+
Returns:
|
|
248
|
+
Resource names grouped by kind.
|
|
249
|
+
"""
|
|
250
|
+
return await (await self._get_provider()).list_resources(skill_id)
|
|
251
|
+
|
|
252
|
+
async def list_files(self, skill_id: str) -> list[str]:
|
|
253
|
+
"""List every file in a skill without reading file contents.
|
|
254
|
+
|
|
255
|
+
Args:
|
|
256
|
+
skill_id: Skill identifier.
|
|
257
|
+
|
|
258
|
+
Returns:
|
|
259
|
+
Sorted POSIX paths relative to the skill root.
|
|
260
|
+
"""
|
|
261
|
+
return await (await self._get_provider()).list_files(skill_id)
|
|
262
|
+
|
|
263
|
+
async def read_file(self, skill_id: str, path: str) -> bytes:
|
|
264
|
+
"""Read one original skill file as bytes.
|
|
265
|
+
|
|
266
|
+
Args:
|
|
267
|
+
skill_id: Skill identifier.
|
|
268
|
+
path: POSIX path relative to the skill root.
|
|
269
|
+
|
|
270
|
+
Returns:
|
|
271
|
+
Original file bytes.
|
|
272
|
+
"""
|
|
273
|
+
return await (await self._get_provider()).read_file(skill_id, path)
|
|
274
|
+
|
|
275
|
+
async def discover(self) -> list[str]:
|
|
276
|
+
"""Return skill IDs directly under the configured repository path.
|
|
277
|
+
|
|
278
|
+
Returns:
|
|
279
|
+
Sorted skill identifiers.
|
|
280
|
+
"""
|
|
281
|
+
return await (await self._get_provider()).discover()
|
|
282
|
+
|
|
283
|
+
async def _get_provider(self) -> LocalFileSystemSkillProvider:
|
|
284
|
+
return await asyncio.to_thread(self._get_provider_sync)
|
|
285
|
+
|
|
286
|
+
def _get_provider_sync(self) -> LocalFileSystemSkillProvider:
|
|
287
|
+
with _CACHE_LOCK, self._lock:
|
|
288
|
+
if self._provider is not None:
|
|
289
|
+
return self._provider
|
|
290
|
+
self.cache_dir.mkdir(parents=True, exist_ok=True)
|
|
291
|
+
with _cache_directory_lock(self.cache_dir):
|
|
292
|
+
root, commit = self._materialize()
|
|
293
|
+
self._create_cache_lease()
|
|
294
|
+
self._provider = LocalFileSystemSkillProvider(root)
|
|
295
|
+
self._resolved_commit = commit
|
|
296
|
+
_ACTIVE_PROVIDERS.add(self)
|
|
297
|
+
return self._provider
|
|
298
|
+
|
|
299
|
+
def _create_cache_lease(self) -> None:
|
|
300
|
+
lease_dir = self.cache_dir / ".leases" / self._cache_path.name
|
|
301
|
+
lease_dir.mkdir(parents=True, exist_ok=True)
|
|
302
|
+
lease_path = lease_dir / f"{os.getpid()}-{uuid.uuid4().hex}"
|
|
303
|
+
stream = lease_path.open("x+b")
|
|
304
|
+
try:
|
|
305
|
+
stream.write(str(os.getpid()).encode("ascii"))
|
|
306
|
+
stream.flush()
|
|
307
|
+
_lock_file(stream, blocking=True)
|
|
308
|
+
except OSError:
|
|
309
|
+
stream.close()
|
|
310
|
+
lease_path.unlink(missing_ok=True)
|
|
311
|
+
raise
|
|
312
|
+
self._lease_finalizer = weakref.finalize(self, _release_cache_lease, stream, lease_path)
|
|
313
|
+
|
|
314
|
+
def _materialize(self) -> tuple[Path, str]:
|
|
315
|
+
self.cache_dir.mkdir(parents=True, exist_ok=True)
|
|
316
|
+
operation = "validate cache"
|
|
317
|
+
if self._cache_path.is_symlink() or self._cache_path.is_junction():
|
|
318
|
+
raise GitSkillProviderError("Git cache entry must not be a link")
|
|
319
|
+
marker = self._cache_path / ".agentskills-git-commit"
|
|
320
|
+
if marker.is_file():
|
|
321
|
+
commit = marker.read_text(encoding="ascii").strip()
|
|
322
|
+
root = self._content_root(self._cache_path)
|
|
323
|
+
if _COMMIT_PATTERN.fullmatch(commit) and root.is_dir():
|
|
324
|
+
self._check_cache_size(self._cache_path)
|
|
325
|
+
self._make_cache_room(0, preserve=self._cache_path)
|
|
326
|
+
os.utime(self._cache_path, None)
|
|
327
|
+
return root, commit
|
|
328
|
+
shutil.rmtree(self._cache_path)
|
|
329
|
+
elif self._cache_path.exists():
|
|
330
|
+
if self._cache_path.is_dir():
|
|
331
|
+
shutil.rmtree(self._cache_path)
|
|
332
|
+
else:
|
|
333
|
+
self._cache_path.unlink()
|
|
334
|
+
|
|
335
|
+
try:
|
|
336
|
+
with tempfile.TemporaryDirectory(prefix="agentskills-git-", dir=self.cache_dir) as temp:
|
|
337
|
+
temporary_root = Path(temp)
|
|
338
|
+
repo_dir = temporary_root / "repo"
|
|
339
|
+
hooks = temporary_root / "hooks"
|
|
340
|
+
template = temporary_root / "template"
|
|
341
|
+
hooks.mkdir()
|
|
342
|
+
template.mkdir()
|
|
343
|
+
global_config = temporary_root / "gitconfig"
|
|
344
|
+
global_config.write_text("", encoding="utf-8")
|
|
345
|
+
env = os.environ.copy()
|
|
346
|
+
env["GIT_CONFIG_NOSYSTEM"] = "1"
|
|
347
|
+
env["GIT_CONFIG_GLOBAL"] = str(global_config)
|
|
348
|
+
operation = "initialize repository"
|
|
349
|
+
self._git(["init", "--quiet", f"--template={template}", str(repo_dir)], env, hooks)
|
|
350
|
+
operation = "configure remote"
|
|
351
|
+
self._git(
|
|
352
|
+
["-C", str(repo_dir), "remote", "add", "origin", self.repository],
|
|
353
|
+
env,
|
|
354
|
+
hooks,
|
|
355
|
+
)
|
|
356
|
+
operation = "fetch revision"
|
|
357
|
+
self._git(
|
|
358
|
+
["-C", str(repo_dir), "fetch", "--quiet", "--depth=1", "origin", self.ref],
|
|
359
|
+
env,
|
|
360
|
+
hooks,
|
|
361
|
+
)
|
|
362
|
+
operation = "resolve commit"
|
|
363
|
+
commit = self._git(
|
|
364
|
+
["-C", str(repo_dir), "rev-parse", "FETCH_HEAD^{commit}"], env, hooks
|
|
365
|
+
).strip()
|
|
366
|
+
if not _COMMIT_PATTERN.fullmatch(commit):
|
|
367
|
+
raise GitSkillProviderError("Git returned an invalid resolved commit")
|
|
368
|
+
operation = "checkout commit"
|
|
369
|
+
self._git(
|
|
370
|
+
["-C", str(repo_dir), "checkout", "--quiet", "--detach", commit], env, hooks
|
|
371
|
+
)
|
|
372
|
+
operation = "remove remote metadata"
|
|
373
|
+
self._git(["-C", str(repo_dir), "remote", "remove", "origin"], env, hooks)
|
|
374
|
+
(repo_dir / ".git" / "FETCH_HEAD").unlink(missing_ok=True)
|
|
375
|
+
operation = "validate skill directory"
|
|
376
|
+
root = self._content_root(repo_dir)
|
|
377
|
+
if not root.is_dir():
|
|
378
|
+
raise GitSkillProviderError(
|
|
379
|
+
"Configured subdirectory does not exist at this commit"
|
|
380
|
+
)
|
|
381
|
+
self._reject_links(root)
|
|
382
|
+
(repo_dir / ".agentskills-git-commit").write_text(commit, encoding="ascii")
|
|
383
|
+
operation = "check checkout size"
|
|
384
|
+
size = self._check_cache_size(repo_dir)
|
|
385
|
+
operation = "make cache room"
|
|
386
|
+
self._make_cache_room(size)
|
|
387
|
+
operation = "promote checkout into cache"
|
|
388
|
+
shutil.move(str(repo_dir), str(self._cache_path))
|
|
389
|
+
return self._content_root(self._cache_path), commit
|
|
390
|
+
except GitSkillProviderError:
|
|
391
|
+
raise
|
|
392
|
+
except (OSError, subprocess.SubprocessError) as exc:
|
|
393
|
+
raise GitSkillProviderError(f"Could not {operation} ({type(exc).__name__})") from None
|
|
394
|
+
|
|
395
|
+
def _git(self, args: list[str], env: dict[str, str], hooks: Path) -> str:
|
|
396
|
+
result = subprocess.run(
|
|
397
|
+
["git", "-c", f"core.hooksPath={hooks}", "-c", "protocol.ext.allow=never", *args],
|
|
398
|
+
capture_output=True,
|
|
399
|
+
check=True,
|
|
400
|
+
env=env,
|
|
401
|
+
text=True,
|
|
402
|
+
timeout=120,
|
|
403
|
+
)
|
|
404
|
+
return result.stdout
|
|
405
|
+
|
|
406
|
+
def _content_root(self, repo_dir: Path) -> Path:
|
|
407
|
+
root = repo_dir.resolve()
|
|
408
|
+
candidate = repo_dir
|
|
409
|
+
for part in self.subdirectory.parts:
|
|
410
|
+
candidate = candidate / part
|
|
411
|
+
if candidate.is_symlink() or candidate.is_junction():
|
|
412
|
+
raise GitSkillProviderError("Configured subdirectory contains a link")
|
|
413
|
+
resolved = candidate.resolve()
|
|
414
|
+
if not resolved.is_relative_to(root):
|
|
415
|
+
raise GitSkillProviderError("Configured subdirectory escapes the checkout")
|
|
416
|
+
return resolved
|
|
417
|
+
|
|
418
|
+
def _check_cache_size(self, repo_dir: Path) -> int:
|
|
419
|
+
size = self._directory_size(repo_dir)
|
|
420
|
+
if size > self.max_cache_bytes:
|
|
421
|
+
raise GitSkillProviderError(
|
|
422
|
+
f"Repository checkout exceeds max_cache_bytes ({self.max_cache_bytes})"
|
|
423
|
+
)
|
|
424
|
+
return size
|
|
425
|
+
|
|
426
|
+
@staticmethod
|
|
427
|
+
def _directory_size(directory: Path) -> int:
|
|
428
|
+
size = 0
|
|
429
|
+
for path in directory.rglob("*"):
|
|
430
|
+
if path.is_symlink() or path.is_junction():
|
|
431
|
+
raise GitSkillProviderError("Repository checkout contains a symbolic link")
|
|
432
|
+
if path.is_file():
|
|
433
|
+
size += path.stat().st_size
|
|
434
|
+
return size
|
|
435
|
+
|
|
436
|
+
def _make_cache_room(self, incoming_size: int, *, preserve: Path | None = None) -> None:
|
|
437
|
+
entries: list[tuple[int, int, Path]] = []
|
|
438
|
+
total_size = 0
|
|
439
|
+
for path in self.cache_dir.iterdir():
|
|
440
|
+
marker = path / ".agentskills-git-commit"
|
|
441
|
+
if path.is_symlink() or path.is_junction() or not path.is_dir() or not marker.is_file():
|
|
442
|
+
continue
|
|
443
|
+
size = self._directory_size(path)
|
|
444
|
+
total_size += size
|
|
445
|
+
entries.append((path.stat().st_mtime_ns, size, path))
|
|
446
|
+
|
|
447
|
+
active_paths = {
|
|
448
|
+
provider._cache_path
|
|
449
|
+
for provider in tuple(_ACTIVE_PROVIDERS)
|
|
450
|
+
if provider._provider is not None
|
|
451
|
+
}
|
|
452
|
+
for _, size, path in sorted(entries):
|
|
453
|
+
if total_size + incoming_size <= self.max_total_cache_bytes:
|
|
454
|
+
break
|
|
455
|
+
if path == preserve or path in active_paths or self._has_active_lease(path):
|
|
456
|
+
continue
|
|
457
|
+
self._remove_cache_entry(path)
|
|
458
|
+
lease_dir = self.cache_dir / ".leases" / path.name
|
|
459
|
+
shutil.rmtree(lease_dir, ignore_errors=True)
|
|
460
|
+
total_size -= size
|
|
461
|
+
|
|
462
|
+
if total_size + incoming_size > self.max_total_cache_bytes:
|
|
463
|
+
raise GitSkillProviderError(
|
|
464
|
+
"Total Git cache exceeds max_total_cache_bytes "
|
|
465
|
+
f"({self.max_total_cache_bytes}); no inactive checkout is available to evict"
|
|
466
|
+
)
|
|
467
|
+
|
|
468
|
+
def _has_active_lease(self, cache_path: Path) -> bool:
|
|
469
|
+
lease_dir = self.cache_dir / ".leases" / cache_path.name
|
|
470
|
+
if not lease_dir.is_dir():
|
|
471
|
+
return False
|
|
472
|
+
active = False
|
|
473
|
+
for lease_path in lease_dir.iterdir():
|
|
474
|
+
stale = False
|
|
475
|
+
try:
|
|
476
|
+
with lease_path.open("r+b") as stream:
|
|
477
|
+
try:
|
|
478
|
+
_lock_file(stream, blocking=False)
|
|
479
|
+
except OSError:
|
|
480
|
+
active = True
|
|
481
|
+
else:
|
|
482
|
+
_unlock_file(stream)
|
|
483
|
+
stale = True
|
|
484
|
+
except FileNotFoundError:
|
|
485
|
+
continue
|
|
486
|
+
if stale:
|
|
487
|
+
lease_path.unlink(missing_ok=True)
|
|
488
|
+
if not active:
|
|
489
|
+
with contextlib.suppress(OSError):
|
|
490
|
+
lease_dir.rmdir()
|
|
491
|
+
return active
|
|
492
|
+
|
|
493
|
+
@staticmethod
|
|
494
|
+
def _remove_cache_entry(path: Path) -> None:
|
|
495
|
+
def retry_read_only(func: Any, target: str, error_info: tuple[Any, ...]) -> None:
|
|
496
|
+
error = error_info[1]
|
|
497
|
+
if not isinstance(error, PermissionError):
|
|
498
|
+
raise error
|
|
499
|
+
os.chmod(target, stat.S_IREAD | stat.S_IWRITE)
|
|
500
|
+
func(target)
|
|
501
|
+
|
|
502
|
+
shutil.rmtree(path, onerror=retry_read_only)
|
|
503
|
+
|
|
504
|
+
@staticmethod
|
|
505
|
+
def _reject_links(repo_dir: Path) -> None:
|
|
506
|
+
for path in repo_dir.rglob("*"):
|
|
507
|
+
if path.is_symlink():
|
|
508
|
+
raise GitSkillProviderError("Repository checkout contains a symbolic link")
|
|
File without changes
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
[tool.poetry]
|
|
2
|
+
name = "agentskills-git"
|
|
3
|
+
version = "0.8.0"
|
|
4
|
+
description = "Git-backed provider for reproducible Agent Skills sources (https://agentskills.io)"
|
|
5
|
+
license = "MIT"
|
|
6
|
+
authors = ["Pratik Panda"]
|
|
7
|
+
readme = "README.md"
|
|
8
|
+
homepage = "https://agentskills.io"
|
|
9
|
+
repository = "https://github.com/pratikxpanda/agentskills-sdk"
|
|
10
|
+
packages = [{include = "agentskills_git"}]
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Development Status :: 3 - Alpha",
|
|
13
|
+
"Intended Audience :: Developers",
|
|
14
|
+
"Topic :: Software Development :: Libraries",
|
|
15
|
+
"Programming Language :: Python :: 3.12",
|
|
16
|
+
"Programming Language :: Python :: 3.13",
|
|
17
|
+
"Programming Language :: Python :: 3.14",
|
|
18
|
+
]
|
|
19
|
+
|
|
20
|
+
[tool.poetry.dependencies]
|
|
21
|
+
python = ">=3.12,<4.0"
|
|
22
|
+
agentskills-core = ">=0.8.0,<1.0"
|
|
23
|
+
agentskills-fs = ">=0.8.0,<1.0"
|
|
24
|
+
|
|
25
|
+
[build-system]
|
|
26
|
+
requires = ["poetry-core"]
|
|
27
|
+
build-backend = "poetry.core.masonry.api"
|