coding-agent-toolchain 1.0.0__py3-none-any.whl
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.
- agent_toolchain/__init__.py +8 -0
- agent_toolchain/errors.py +108 -0
- agent_toolchain/git_io.py +284 -0
- agent_toolchain/json_io.py +55 -0
- agent_toolchain/tool_skill_sync.py +3050 -0
- agent_toolchain/tool_temp_dir.py +1057 -0
- agent_toolchain/workflow_health.py +501 -0
- coding_agent_toolchain-1.0.0.dist-info/METADATA +103 -0
- coding_agent_toolchain-1.0.0.dist-info/RECORD +12 -0
- coding_agent_toolchain-1.0.0.dist-info/WHEEL +4 -0
- coding_agent_toolchain-1.0.0.dist-info/entry_points.txt +4 -0
- coding_agent_toolchain-1.0.0.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,3050 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Validate and atomically stage versioned tool/binary Skill pairs."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import argparse
|
|
7
|
+
import ast
|
|
8
|
+
import base64
|
|
9
|
+
from collections.abc import Sequence
|
|
10
|
+
from contextlib import contextmanager
|
|
11
|
+
import fcntl
|
|
12
|
+
import hashlib
|
|
13
|
+
import io
|
|
14
|
+
import json
|
|
15
|
+
import os
|
|
16
|
+
from pathlib import Path
|
|
17
|
+
import re
|
|
18
|
+
import shutil
|
|
19
|
+
import stat
|
|
20
|
+
import subprocess
|
|
21
|
+
import sys
|
|
22
|
+
import tarfile
|
|
23
|
+
import tempfile
|
|
24
|
+
import time
|
|
25
|
+
import tomllib
|
|
26
|
+
from typing import Any
|
|
27
|
+
|
|
28
|
+
VERSION = "1.0.0"
|
|
29
|
+
SCHEMA_VERSION = 1
|
|
30
|
+
TOOL_SKILL_MANIFEST_SCHEMA_VERSION = 2
|
|
31
|
+
SKILL_NAME = "git-change-delivery"
|
|
32
|
+
COMPATIBILITY_SKILL_NAME = "three-tool-git-workflow"
|
|
33
|
+
COMPATIBILITY_BUNDLE_PATH = (
|
|
34
|
+
Path("compatibility") / COMPATIBILITY_SKILL_NAME / "SKILL.md"
|
|
35
|
+
)
|
|
36
|
+
SKILL_PAYLOAD = (
|
|
37
|
+
"SKILL.md",
|
|
38
|
+
"quick_validate.py",
|
|
39
|
+
"unpublished_queue.py",
|
|
40
|
+
"references/context-loader.md",
|
|
41
|
+
"references/git-finalizer.md",
|
|
42
|
+
"references/snapshot-runner.md",
|
|
43
|
+
"references/unpublished-queue.md",
|
|
44
|
+
)
|
|
45
|
+
HEX_SHA256 = re.compile(r"[0-9a-f]{64}\Z")
|
|
46
|
+
FULL_GIT_OID = re.compile(r"[0-9a-f]{40,64}\Z")
|
|
47
|
+
SAFE_NAME = re.compile(r"[a-z0-9][a-z0-9._-]*\Z")
|
|
48
|
+
VERSION_LITERAL_RE = re.compile(r"[0-9]+\.[0-9]+\.[0-9]+\Z")
|
|
49
|
+
DEFAULT_LOCK_TIMEOUT = 10.0
|
|
50
|
+
# Payload-tree digests of previously released canonical Skill lines that may
|
|
51
|
+
# legally sit in production before an upgrade. Never add a digest produced by
|
|
52
|
+
# local hand-editing. Keep RELEASED_CANONICAL_SKILL_SHA256 strictly bound to
|
|
53
|
+
# digests published in tagged/integrated git history.
|
|
54
|
+
RELEASED_CANONICAL_SKILL_SHA256 = frozenset(
|
|
55
|
+
{
|
|
56
|
+
# Provider-neutral payload of the first shipped canonical line.
|
|
57
|
+
"ff6d5bea2807b2c884c2ec5bee441e5fe8060abd9d03c0520c57ce39fe37adb5",
|
|
58
|
+
# Canonical payload carried by the two tagged releases of that line.
|
|
59
|
+
"3c8679b6cfd6578da41007feeea43e7ff83e8152e3daea9ab9154055642a92e2",
|
|
60
|
+
# Canonical payload carried by the merged live-policy release.
|
|
61
|
+
"7b85ec9da739bd60f76736ae6352e642dbf880bbd089058cce4cf7a9c0b5c665",
|
|
62
|
+
# Canonical payload carried by the handoff-documentation release, which
|
|
63
|
+
# is also the installed production tree this batch upgrades from.
|
|
64
|
+
"9c05e5b279731a37b3ce15e2fbda7ae9962f81355cbafb86fa410f28ec19f527",
|
|
65
|
+
# Canonical payload carried by the integration-boundary release and by
|
|
66
|
+
# the first publicly released line after it; both tags shipped it
|
|
67
|
+
# unchanged, so a production tree holding it is released lineage.
|
|
68
|
+
"0c82bceb12edde749aa6deddab25acb4ec083aeea92a37970ec64179ef92726b",
|
|
69
|
+
# Payload independently attested by the next published tag.
|
|
70
|
+
"943ebf4e56ae344cf88ab3dc579d5e497663b052c8ccbade5c42f1f52b5efa93",
|
|
71
|
+
# Published canonical payload at commit 67e3e6c.
|
|
72
|
+
"288d3126d9459913714aa2e3934773111b2d4430fb73a8385fd33511807a823c",
|
|
73
|
+
# Published canonical payload at v1.9.9 (ceae77f).
|
|
74
|
+
"010cb09faf50921149b5d22b26093d9445d15461e8d3f10b7faff35259cd8e45",
|
|
75
|
+
# Published canonical payload at git-finalizer v2.0.0.
|
|
76
|
+
"d1525f9aeb9dcdda18fc9a5e8914ba3ba7c7ed26d9ec5463ca1359b428940bf1",
|
|
77
|
+
}
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
class SyncError(Exception):
|
|
82
|
+
"""A validation or safe activation condition was not met."""
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def canonical_json(value: Any) -> bytes:
|
|
86
|
+
return (
|
|
87
|
+
json.dumps(value, ensure_ascii=False, sort_keys=True, indent=2) + "\n"
|
|
88
|
+
).encode()
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def sha256_bytes(value: bytes) -> str:
|
|
92
|
+
return hashlib.sha256(value).hexdigest()
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def sha256_file(path: Path) -> str:
|
|
96
|
+
digest = hashlib.sha256()
|
|
97
|
+
with path.open("rb") as stream:
|
|
98
|
+
for chunk in iter(lambda: stream.read(1024 * 1024), b""):
|
|
99
|
+
digest.update(chunk)
|
|
100
|
+
return digest.hexdigest()
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def read_json(path: Path) -> dict[str, Any]:
|
|
104
|
+
try:
|
|
105
|
+
raw = path.read_bytes()
|
|
106
|
+
value = json.loads(raw.decode("utf-8"))
|
|
107
|
+
except (OSError, UnicodeError, json.JSONDecodeError) as exc:
|
|
108
|
+
raise SyncError(f"invalid JSON {path}: {exc}") from exc
|
|
109
|
+
if not isinstance(value, dict):
|
|
110
|
+
raise SyncError(f"JSON root must be an object: {path}")
|
|
111
|
+
if raw != canonical_json(value):
|
|
112
|
+
raise SyncError(f"JSON is not deterministically serialized: {path}")
|
|
113
|
+
return value
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def write_json(path: Path, value: dict[str, Any], mode: int = 0o600) -> None:
|
|
117
|
+
path.write_bytes(canonical_json(value))
|
|
118
|
+
path.chmod(mode)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def require_regular(path: Path, label: str) -> None:
|
|
122
|
+
if path.is_symlink() or not path.is_file():
|
|
123
|
+
raise SyncError(f"{label} is not a regular file: {path}")
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def require_owned_directory(path: Path, *, create: bool = False) -> None:
|
|
127
|
+
if create and not path.exists():
|
|
128
|
+
path.mkdir(mode=0o700, parents=True)
|
|
129
|
+
if path.is_symlink() or not path.is_dir():
|
|
130
|
+
raise SyncError(f"directory is missing or unsafe: {path}")
|
|
131
|
+
if path.stat().st_uid != os.getuid():
|
|
132
|
+
raise SyncError(f"directory is not owned by current user: {path}")
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def _flock_exclusive_bounded(descriptor: int, *, timeout: float = DEFAULT_LOCK_TIMEOUT, label: str = "lock") -> None:
|
|
136
|
+
deadline = time.monotonic() + timeout
|
|
137
|
+
while True:
|
|
138
|
+
try:
|
|
139
|
+
fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
|
140
|
+
return
|
|
141
|
+
except BlockingIOError as exc:
|
|
142
|
+
if time.monotonic() >= deadline:
|
|
143
|
+
raise SyncError(f"timed out waiting for {label}") from exc
|
|
144
|
+
time.sleep(0.05)
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
@contextmanager
|
|
148
|
+
def deployment_lock(*roots: Path, timeout: float = DEFAULT_LOCK_TIMEOUT):
|
|
149
|
+
"""Serialize installers through the same persistent locks, including rollback."""
|
|
150
|
+
descriptors = []
|
|
151
|
+
try:
|
|
152
|
+
for root in sorted({path.absolute() for path in roots}):
|
|
153
|
+
require_owned_directory(root, create=True)
|
|
154
|
+
descriptor = os.open(
|
|
155
|
+
root / ".tool-skill-sync.lock",
|
|
156
|
+
os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW | os.O_CLOEXEC,
|
|
157
|
+
0o600,
|
|
158
|
+
)
|
|
159
|
+
descriptors.append(descriptor)
|
|
160
|
+
info = os.fstat(descriptor)
|
|
161
|
+
if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
|
|
162
|
+
raise SyncError("unsafe deployment lock")
|
|
163
|
+
_flock_exclusive_bounded(descriptor, timeout=timeout, label="deployment lock")
|
|
164
|
+
yield
|
|
165
|
+
finally:
|
|
166
|
+
for descriptor in reversed(descriptors):
|
|
167
|
+
os.close(descriptor)
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def tree_sha256(root: Path, relative_paths: Sequence[str]) -> str:
|
|
171
|
+
lines: list[str] = []
|
|
172
|
+
for relative in relative_paths:
|
|
173
|
+
path = root / relative
|
|
174
|
+
require_regular(path, "Skill payload")
|
|
175
|
+
lines.append(f"{sha256_file(path)} {relative}\n")
|
|
176
|
+
return sha256_bytes("".join(lines).encode())
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
def aggregate_hash(values: dict[str, str]) -> str:
|
|
180
|
+
return sha256_bytes(canonical_json(values))
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def run(
|
|
184
|
+
arguments: Sequence[str],
|
|
185
|
+
*,
|
|
186
|
+
cwd: Path | None = None,
|
|
187
|
+
env: dict[str, str] | None = None,
|
|
188
|
+
) -> subprocess.CompletedProcess[str]:
|
|
189
|
+
return subprocess.run(
|
|
190
|
+
arguments,
|
|
191
|
+
cwd=cwd,
|
|
192
|
+
env=env,
|
|
193
|
+
check=False,
|
|
194
|
+
capture_output=True,
|
|
195
|
+
text=True,
|
|
196
|
+
timeout=30,
|
|
197
|
+
)
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def git(repo: Path, *arguments: str) -> str:
|
|
201
|
+
result = run(("git", "-C", str(repo), *arguments))
|
|
202
|
+
if result.returncode != 0:
|
|
203
|
+
detail = result.stderr.strip() or result.stdout.strip() or "unknown git error"
|
|
204
|
+
raise SyncError(f"git {' '.join(arguments)} failed for {repo}: {detail}")
|
|
205
|
+
return result.stdout.strip()
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
def git_head(repo: Path) -> str:
|
|
209
|
+
head = git(repo, "rev-parse", "HEAD")
|
|
210
|
+
if not FULL_GIT_OID.fullmatch(head):
|
|
211
|
+
raise SyncError(f"repository HEAD is not a full object id: {repo}")
|
|
212
|
+
return head
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
def git_dirty(repo: Path) -> bool:
|
|
216
|
+
environment = os.environ.copy()
|
|
217
|
+
environment["GIT_OPTIONAL_LOCKS"] = "0"
|
|
218
|
+
result = run(
|
|
219
|
+
("git", "-C", str(repo), "status", "--porcelain=v1", "--untracked-files=all"),
|
|
220
|
+
env=environment,
|
|
221
|
+
)
|
|
222
|
+
if result.returncode != 0:
|
|
223
|
+
detail = result.stderr.strip() or result.stdout.strip() or "unknown git error"
|
|
224
|
+
raise SyncError(f"git status failed for {repo}: {detail}")
|
|
225
|
+
return bool(result.stdout.strip())
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def project_version(repo: Path, tool_name: str, *, kind: str | None = None) -> tuple[str, tuple[str, ...]]:
|
|
229
|
+
pyproject = repo / "pyproject.toml"
|
|
230
|
+
use_pyproject = kind == "python_console_scripts" or (
|
|
231
|
+
kind is None
|
|
232
|
+
and tool_name in {"agent-toolchain", "context-loader", "snapshot-runner", "git-finalizer"}
|
|
233
|
+
and pyproject.is_file()
|
|
234
|
+
)
|
|
235
|
+
if use_pyproject:
|
|
236
|
+
require_regular(pyproject, "project metadata")
|
|
237
|
+
with pyproject.open("rb") as stream:
|
|
238
|
+
data = tomllib.load(stream)
|
|
239
|
+
version = data.get("project", {}).get("version")
|
|
240
|
+
scripts = data.get("project", {}).get("scripts", {})
|
|
241
|
+
if not isinstance(version, str) or not isinstance(scripts, dict):
|
|
242
|
+
raise SyncError(f"invalid project version/scripts: {pyproject}")
|
|
243
|
+
return version, tuple(sorted(str(name) for name in scripts))
|
|
244
|
+
|
|
245
|
+
manifest_candidates = (
|
|
246
|
+
repo / "tool_skill_manifest.json",
|
|
247
|
+
repo / "manifests" / tool_name / "tool_skill_manifest.json",
|
|
248
|
+
)
|
|
249
|
+
manifest_path = next((p for p in manifest_candidates if p.exists()), manifest_candidates[0])
|
|
250
|
+
manifest = read_json(manifest_path)
|
|
251
|
+
entrypoints = validate_install_targets(manifest)
|
|
252
|
+
if manifest["executable"]["kind"] == "python_console_scripts":
|
|
253
|
+
return project_version(repo, tool_name, kind="python_console_scripts")
|
|
254
|
+
executable = repo / entrypoints[0]
|
|
255
|
+
require_regular(executable, "Git Finalizer executable")
|
|
256
|
+
match = re.search(
|
|
257
|
+
rb"(?m)^(?:readonly )?(?:VERSION|__version__)\s*=\s*['\"]([0-9]+\.[0-9]+\.[0-9]+)['\"]$",
|
|
258
|
+
executable.read_bytes(),
|
|
259
|
+
)
|
|
260
|
+
if match is None:
|
|
261
|
+
raise SyncError("cannot read source version")
|
|
262
|
+
return match.group(1).decode(), tuple(sorted(entrypoints))
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
class Sources:
|
|
266
|
+
def __init__(
|
|
267
|
+
self, source_root: Path, source_repos: dict[str, Path] | None = None,
|
|
268
|
+
source_refs: dict[str, str] | None = None,
|
|
269
|
+
) -> None:
|
|
270
|
+
self.source_root = source_root.resolve()
|
|
271
|
+
self.source_refs = dict(source_refs or {})
|
|
272
|
+
self.source_repos = {
|
|
273
|
+
name: path.resolve() for name, path in (source_repos or {}).items()
|
|
274
|
+
}
|
|
275
|
+
self.owner_repo = self.source_repos.get(
|
|
276
|
+
"git-finalizer", self.source_root / "git-finalizer"
|
|
277
|
+
)
|
|
278
|
+
require_owned_directory(self.owner_repo)
|
|
279
|
+
self.compatibility_path = self.owner_repo / "toolchain_compatibility.json"
|
|
280
|
+
self.compatibility = read_json(self.compatibility_path)
|
|
281
|
+
if self.compatibility.get("schema_version") != SCHEMA_VERSION:
|
|
282
|
+
raise SyncError("unsupported toolchain compatibility schema_version")
|
|
283
|
+
workflow_skill = self.compatibility.get("workflow_skill")
|
|
284
|
+
if workflow_skill != {
|
|
285
|
+
"name": SKILL_NAME,
|
|
286
|
+
"contract_version": workflow_skill.get("contract_version")
|
|
287
|
+
if isinstance(workflow_skill, dict) else None,
|
|
288
|
+
"canonical_owner": "git-finalizer",
|
|
289
|
+
"compatibility_shims": [COMPATIBILITY_SKILL_NAME],
|
|
290
|
+
}:
|
|
291
|
+
raise SyncError("toolchain workflow Skill binding is unrecognized")
|
|
292
|
+
if workflow_skill["contract_version"] not in {1, 2}:
|
|
293
|
+
raise SyncError("unsupported workflow Skill contract version")
|
|
294
|
+
tools = self.compatibility.get("tools")
|
|
295
|
+
if not isinstance(tools, dict) or not tools:
|
|
296
|
+
raise SyncError("toolchain compatibility contract has no tools")
|
|
297
|
+
self.tool_config = tools
|
|
298
|
+
if (set(self.source_repos) | set(self.source_refs)) - set(tools):
|
|
299
|
+
raise SyncError("source-repo names an unknown tool")
|
|
300
|
+
self.skill_root = self.owner_repo / "skills" / SKILL_NAME
|
|
301
|
+
self.compatibility_skill_root = (
|
|
302
|
+
self.owner_repo / "skills" / COMPATIBILITY_SKILL_NAME
|
|
303
|
+
)
|
|
304
|
+
|
|
305
|
+
def head(self, tool: str) -> str:
|
|
306
|
+
return self.source_refs.get(tool) or git_head(self.repo(tool))
|
|
307
|
+
|
|
308
|
+
def dirty(self, tool: str) -> bool:
|
|
309
|
+
return False if tool in self.source_refs else git_dirty(self.repo(tool))
|
|
310
|
+
|
|
311
|
+
def source_bytes(self, tool: str, relative: str) -> bytes:
|
|
312
|
+
repo = self.repo(tool)
|
|
313
|
+
if tool not in self.source_refs:
|
|
314
|
+
return (repo / relative).read_bytes()
|
|
315
|
+
if relative not in {"pyproject.toml", "tool_cli_contract.json"}:
|
|
316
|
+
raise SyncError("pinned source reads are limited to package metadata and contract")
|
|
317
|
+
oid = self.source_refs[tool]
|
|
318
|
+
if not FULL_GIT_OID.fullmatch(oid):
|
|
319
|
+
raise SyncError("source-ref requires a full commit OID")
|
|
320
|
+
manifest = read_json(self.manifest_path(tool))
|
|
321
|
+
if manifest["executable"]["kind"] != "python_console_scripts":
|
|
322
|
+
raise SyncError("source-ref only supports released Python console-script metadata")
|
|
323
|
+
if git(repo, "rev-parse", f"{oid}^{{commit}}") != oid:
|
|
324
|
+
raise SyncError("source-ref must identify a commit, not a tag object")
|
|
325
|
+
result = subprocess.run(
|
|
326
|
+
["git", "-C", str(repo), "show", f"{oid}:{relative}"],
|
|
327
|
+
capture_output=True, check=False, timeout=30,
|
|
328
|
+
)
|
|
329
|
+
if result.returncode:
|
|
330
|
+
raise SyncError(f"pinned source file is unavailable: {tool}/{relative}")
|
|
331
|
+
return result.stdout
|
|
332
|
+
|
|
333
|
+
def project_identity(self, tool: str, *, kind: str | None = None) -> tuple[str, tuple[str, ...]]:
|
|
334
|
+
if tool not in self.source_refs:
|
|
335
|
+
return project_version(self.repo(tool), tool, kind=kind)
|
|
336
|
+
data = tomllib.loads(self.source_bytes(tool, "pyproject.toml").decode())
|
|
337
|
+
return data["project"]["version"], tuple(sorted(data["project"]["scripts"]))
|
|
338
|
+
|
|
339
|
+
def names(self) -> tuple[str, ...]:
|
|
340
|
+
return tuple(sorted(self.tool_config))
|
|
341
|
+
|
|
342
|
+
def repo(self, tool: str) -> Path:
|
|
343
|
+
config = self.tool_config.get(tool)
|
|
344
|
+
if not isinstance(config, dict):
|
|
345
|
+
raise SyncError(f"unknown tool: {tool}")
|
|
346
|
+
if tool in self.source_repos:
|
|
347
|
+
repo = self.source_repos[tool]
|
|
348
|
+
require_owned_directory(repo)
|
|
349
|
+
return repo
|
|
350
|
+
source_directory = config.get("source_directory")
|
|
351
|
+
if not isinstance(source_directory, str) or not SAFE_NAME.fullmatch(
|
|
352
|
+
source_directory
|
|
353
|
+
):
|
|
354
|
+
raise SyncError(f"unsafe source directory for {tool}")
|
|
355
|
+
repo = (self.source_root / source_directory).resolve()
|
|
356
|
+
if repo.parent != self.source_root:
|
|
357
|
+
raise SyncError(f"source directory escapes source root for {tool}")
|
|
358
|
+
require_owned_directory(repo)
|
|
359
|
+
return repo
|
|
360
|
+
|
|
361
|
+
def manifest_path(self, tool: str) -> Path:
|
|
362
|
+
config = self.tool_config.get(tool, {})
|
|
363
|
+
manifest_rel = config.get("skill_manifest")
|
|
364
|
+
if manifest_rel:
|
|
365
|
+
return (self.owner_repo / manifest_rel).resolve()
|
|
366
|
+
repo = self.repo(tool)
|
|
367
|
+
repo_manifest = repo / "tool_skill_manifest.json"
|
|
368
|
+
if repo_manifest.exists():
|
|
369
|
+
return repo_manifest
|
|
370
|
+
internal_manifest = (
|
|
371
|
+
self.owner_repo / "manifests" / tool / "tool_skill_manifest.json"
|
|
372
|
+
)
|
|
373
|
+
if internal_manifest.exists():
|
|
374
|
+
return internal_manifest
|
|
375
|
+
return repo_manifest
|
|
376
|
+
|
|
377
|
+
|
|
378
|
+
def validate_install_targets(
|
|
379
|
+
manifest: dict[str, Any], *, allow_legacy: bool = False
|
|
380
|
+
) -> tuple[str, ...]:
|
|
381
|
+
executable = manifest.get("executable")
|
|
382
|
+
install_targets = manifest.get("install_targets")
|
|
383
|
+
if not isinstance(executable, dict) or not isinstance(install_targets, dict):
|
|
384
|
+
raise SyncError("manifest executable/install_targets must be objects")
|
|
385
|
+
kind = executable.get("kind")
|
|
386
|
+
if kind not in {"python_console_scripts", "source_files"}:
|
|
387
|
+
raise SyncError(f"unsupported executable kind: {kind}")
|
|
388
|
+
entrypoints = executable.get("entrypoints")
|
|
389
|
+
stable_entries = install_targets.get("stable_entries")
|
|
390
|
+
if (
|
|
391
|
+
not isinstance(entrypoints, list)
|
|
392
|
+
or not entrypoints
|
|
393
|
+
or not isinstance(stable_entries, list)
|
|
394
|
+
or tuple(entrypoints) != tuple(stable_entries)
|
|
395
|
+
):
|
|
396
|
+
raise SyncError("manifest entrypoints and stable_entries must match")
|
|
397
|
+
if any(
|
|
398
|
+
not isinstance(name, str) or not SAFE_NAME.fullmatch(name)
|
|
399
|
+
for name in entrypoints
|
|
400
|
+
):
|
|
401
|
+
raise SyncError("manifest contains unsafe entrypoint")
|
|
402
|
+
expected_skill = SKILL_NAME
|
|
403
|
+
if allow_legacy and manifest.get("schema_version") == 1:
|
|
404
|
+
expected_skill = COMPATIBILITY_SKILL_NAME
|
|
405
|
+
if install_targets.get("skill_directory") != expected_skill:
|
|
406
|
+
raise SyncError("manifest has unrecognized Skill install target")
|
|
407
|
+
if kind == "source_files":
|
|
408
|
+
paths = executable.get("paths")
|
|
409
|
+
if not isinstance(paths, list) or not paths:
|
|
410
|
+
raise SyncError("source_files executable requires paths")
|
|
411
|
+
if any(
|
|
412
|
+
not isinstance(path, str)
|
|
413
|
+
or Path(path).is_absolute()
|
|
414
|
+
or ".." in Path(path).parts
|
|
415
|
+
for path in paths
|
|
416
|
+
):
|
|
417
|
+
raise SyncError("manifest contains unsafe executable source path")
|
|
418
|
+
production_targets = executable.get("production_targets")
|
|
419
|
+
if not isinstance(production_targets, dict) or set(production_targets) != set(
|
|
420
|
+
paths
|
|
421
|
+
):
|
|
422
|
+
raise SyncError(
|
|
423
|
+
"source_files executable requires one production target per path"
|
|
424
|
+
)
|
|
425
|
+
for relative in production_targets.values():
|
|
426
|
+
if (
|
|
427
|
+
not isinstance(relative, str)
|
|
428
|
+
or Path(relative).is_absolute()
|
|
429
|
+
or ".." in Path(relative).parts
|
|
430
|
+
or not Path(relative).parts
|
|
431
|
+
or Path(relative).parts[0] not in {"bin", "hooks"}
|
|
432
|
+
):
|
|
433
|
+
raise SyncError("manifest contains unsafe production target")
|
|
434
|
+
elif "production_targets" in executable:
|
|
435
|
+
raise SyncError("python_console_scripts must not declare production targets")
|
|
436
|
+
return tuple(str(name) for name in entrypoints)
|
|
437
|
+
|
|
438
|
+
|
|
439
|
+
def validate_contract_shape(contract: dict[str, Any]) -> None:
|
|
440
|
+
commands = contract.get("commands")
|
|
441
|
+
operation_classes = contract.get("operation_classes")
|
|
442
|
+
protected_operations = contract.get("protected_operations")
|
|
443
|
+
if not isinstance(commands, list) or not commands:
|
|
444
|
+
raise SyncError("public CLI contract must contain commands")
|
|
445
|
+
if not isinstance(operation_classes, list) or not operation_classes:
|
|
446
|
+
raise SyncError("public CLI contract must contain operation_classes")
|
|
447
|
+
if not isinstance(protected_operations, list):
|
|
448
|
+
raise SyncError("public CLI contract protected_operations must be a list")
|
|
449
|
+
allowed_classes = {"read_only", "local_mutation", "remote_mutation"}
|
|
450
|
+
if not set(operation_classes) <= allowed_classes:
|
|
451
|
+
raise SyncError("public CLI contract has an unknown operation_class")
|
|
452
|
+
names: set[str] = set()
|
|
453
|
+
for command in commands:
|
|
454
|
+
if not isinstance(command, dict):
|
|
455
|
+
raise SyncError("public CLI contract command must be an object")
|
|
456
|
+
name = command.get("name")
|
|
457
|
+
if not isinstance(name, str) or not SAFE_NAME.fullmatch(name) or name in names:
|
|
458
|
+
raise SyncError("public CLI contract command name is invalid or duplicated")
|
|
459
|
+
names.add(name)
|
|
460
|
+
if command.get("operation_class") not in operation_classes:
|
|
461
|
+
raise SyncError("command operation_class is not declared")
|
|
462
|
+
for key in ("flags", "preconditions", "result_statuses"):
|
|
463
|
+
if not isinstance(command.get(key), list):
|
|
464
|
+
raise SyncError(f"public CLI contract command {key} must be a list")
|
|
465
|
+
|
|
466
|
+
|
|
467
|
+
def validate_manifest_static_fields(
|
|
468
|
+
manifest: dict[str, Any], *, allow_legacy: bool = False
|
|
469
|
+
) -> None:
|
|
470
|
+
required = {
|
|
471
|
+
"schema_version",
|
|
472
|
+
"tool_name",
|
|
473
|
+
"tool_version",
|
|
474
|
+
"tool_commit",
|
|
475
|
+
"skill_contract_version",
|
|
476
|
+
"public_cli_contract_sha256",
|
|
477
|
+
"canonical_skill_sha256",
|
|
478
|
+
"compatible_toolchain_contract_version",
|
|
479
|
+
"canonical_skill",
|
|
480
|
+
"executable",
|
|
481
|
+
"install_targets",
|
|
482
|
+
}
|
|
483
|
+
legacy = allow_legacy and manifest.get("schema_version") == 1
|
|
484
|
+
if not legacy:
|
|
485
|
+
required.add("compatibility_skill")
|
|
486
|
+
if set(manifest) != required:
|
|
487
|
+
raise SyncError("ToolSkillManifest fields do not match its schema")
|
|
488
|
+
for key in ("public_cli_contract_sha256", "canonical_skill_sha256"):
|
|
489
|
+
if not isinstance(manifest.get(key), str) or not HEX_SHA256.fullmatch(
|
|
490
|
+
manifest[key]
|
|
491
|
+
):
|
|
492
|
+
raise SyncError(f"ToolSkillManifest {key} is not SHA-256")
|
|
493
|
+
expected_name = COMPATIBILITY_SKILL_NAME if legacy else SKILL_NAME
|
|
494
|
+
canonical_skill = manifest.get("canonical_skill")
|
|
495
|
+
if canonical_skill != {
|
|
496
|
+
"owner": "git-finalizer",
|
|
497
|
+
"path": f"skills/{expected_name}/SKILL.md",
|
|
498
|
+
}:
|
|
499
|
+
raise SyncError("ToolSkillManifest canonical Skill authority is unrecognized")
|
|
500
|
+
if legacy:
|
|
501
|
+
return
|
|
502
|
+
compatibility_skill = manifest.get("compatibility_skill")
|
|
503
|
+
if (
|
|
504
|
+
not isinstance(compatibility_skill, dict)
|
|
505
|
+
or set(compatibility_skill) != {"name", "path", "sha256"}
|
|
506
|
+
or compatibility_skill.get("name") != COMPATIBILITY_SKILL_NAME
|
|
507
|
+
or compatibility_skill.get("path")
|
|
508
|
+
!= f"skills/{COMPATIBILITY_SKILL_NAME}/SKILL.md"
|
|
509
|
+
):
|
|
510
|
+
raise SyncError("ToolSkillManifest compatibility Skill binding is invalid")
|
|
511
|
+
digest = compatibility_skill.get("sha256")
|
|
512
|
+
if not isinstance(digest, str) or not HEX_SHA256.fullmatch(digest):
|
|
513
|
+
raise SyncError("ToolSkillManifest compatibility Skill SHA is invalid")
|
|
514
|
+
|
|
515
|
+
|
|
516
|
+
def validate_controller_requirements(requirements: Any) -> None:
|
|
517
|
+
keys = {"cli_contract_versions", "storage_layout_versions", "capability_versions"}
|
|
518
|
+
if not isinstance(requirements, dict) or set(requirements) != keys:
|
|
519
|
+
raise SyncError("missing or malformed reviewed Controller runtime requirements")
|
|
520
|
+
for key in ("cli_contract_versions", "storage_layout_versions"):
|
|
521
|
+
values = requirements[key]
|
|
522
|
+
if (not isinstance(values, list) or not values
|
|
523
|
+
or any(type(value) is not int or value <= 0 for value in values)
|
|
524
|
+
or len(set(values)) != len(values)):
|
|
525
|
+
raise SyncError(f"invalid Controller {key}")
|
|
526
|
+
capabilities = requirements["capability_versions"]
|
|
527
|
+
if not isinstance(capabilities, dict) or "capabilities_version" not in capabilities:
|
|
528
|
+
raise SyncError("Controller capability_versions must bind capabilities_version")
|
|
529
|
+
for name, value in capabilities.items():
|
|
530
|
+
if (not isinstance(name, str) or not re.fullmatch(r"[a-z][a-z0-9_]*_version", name)
|
|
531
|
+
or type(value) is not int or value <= 0):
|
|
532
|
+
raise SyncError("invalid Controller capability version binding")
|
|
533
|
+
|
|
534
|
+
|
|
535
|
+
def check_tool(sources: Sources, tool: str) -> dict[str, Any]:
|
|
536
|
+
errors: list[str] = []
|
|
537
|
+
repo = sources.repo(tool)
|
|
538
|
+
manifest_path = sources.manifest_path(tool)
|
|
539
|
+
try:
|
|
540
|
+
manifest = read_json(manifest_path)
|
|
541
|
+
raw_contract = sources.source_bytes(tool, "tool_cli_contract.json")
|
|
542
|
+
contract = json.loads(raw_contract.decode("utf-8"))
|
|
543
|
+
if not isinstance(contract, dict) or canonical_json(contract) != raw_contract:
|
|
544
|
+
raise SyncError("source contract is not deterministically serialized")
|
|
545
|
+
if manifest.get("schema_version") != TOOL_SKILL_MANIFEST_SCHEMA_VERSION:
|
|
546
|
+
raise SyncError("unsupported ToolSkillManifest schema_version")
|
|
547
|
+
if contract.get("schema_version") != SCHEMA_VERSION:
|
|
548
|
+
raise SyncError("unsupported public CLI contract schema_version")
|
|
549
|
+
if manifest.get("tool_name") != tool or contract.get("tool_name") != tool:
|
|
550
|
+
raise SyncError("tool_name mismatch")
|
|
551
|
+
validate_manifest_static_fields(manifest)
|
|
552
|
+
validate_contract_shape(contract)
|
|
553
|
+
if manifest.get("tool_version") != contract.get("tool_version"):
|
|
554
|
+
raise SyncError("tool version mismatch between manifest and CLI contract")
|
|
555
|
+
source_version, source_entrypoints = sources.project_identity(
|
|
556
|
+
tool, kind=manifest.get("executable", {}).get("kind")
|
|
557
|
+
)
|
|
558
|
+
if source_version != manifest.get("tool_version"):
|
|
559
|
+
raise SyncError("source version does not match ToolSkillManifest")
|
|
560
|
+
entrypoints = validate_install_targets(manifest)
|
|
561
|
+
if tuple(sorted(entrypoints)) != source_entrypoints:
|
|
562
|
+
raise SyncError("source public entrypoints do not match ToolSkillManifest")
|
|
563
|
+
if manifest.get("tool_commit") != "@release":
|
|
564
|
+
raise SyncError("canonical source manifest tool_commit must be @release")
|
|
565
|
+
sources.head(tool)
|
|
566
|
+
contract_sha = sha256_bytes(raw_contract)
|
|
567
|
+
if manifest.get("public_cli_contract_sha256") != contract_sha:
|
|
568
|
+
raise SyncError("public CLI contract SHA mismatch")
|
|
569
|
+
skill_sha = tree_sha256(sources.skill_root, SKILL_PAYLOAD)
|
|
570
|
+
if manifest.get("canonical_skill_sha256") != skill_sha:
|
|
571
|
+
raise SyncError("canonical Skill payload SHA mismatch")
|
|
572
|
+
compatibility_sha = sha256_file(sources.compatibility_skill_root / "SKILL.md")
|
|
573
|
+
if manifest["compatibility_skill"]["sha256"] != compatibility_sha:
|
|
574
|
+
raise SyncError("compatibility Skill SHA mismatch")
|
|
575
|
+
compatibility_version = sources.compatibility.get("toolchain_contract_version")
|
|
576
|
+
if compatibility_version not in {1, 2, 3, 4, 5, 6}:
|
|
577
|
+
raise SyncError("unsupported toolchain compatibility contract version")
|
|
578
|
+
if compatibility_version == 6:
|
|
579
|
+
runtime_requirements = sources.compatibility.get("runtime_requirements")
|
|
580
|
+
if not isinstance(runtime_requirements, dict):
|
|
581
|
+
raise SyncError("v6 requires explicit runtime_requirements")
|
|
582
|
+
validate_controller_requirements(runtime_requirements.get("worktree-controller"))
|
|
583
|
+
if (
|
|
584
|
+
manifest.get("compatible_toolchain_contract_version")
|
|
585
|
+
!= compatibility_version
|
|
586
|
+
):
|
|
587
|
+
raise SyncError("toolchain compatibility version mismatch")
|
|
588
|
+
config = sources.tool_config[tool]
|
|
589
|
+
if contract.get("contract_version") != config.get(
|
|
590
|
+
"public_cli_contract_version"
|
|
591
|
+
):
|
|
592
|
+
raise SyncError("public contract version is incompatible with workflow")
|
|
593
|
+
compatibility_key = tool.replace("-", "_") + "_contract_version"
|
|
594
|
+
if sources.compatibility.get(compatibility_key) != config.get(
|
|
595
|
+
"public_cli_contract_version"
|
|
596
|
+
):
|
|
597
|
+
raise SyncError("top-level toolchain contract binding is inconsistent")
|
|
598
|
+
if manifest.get("skill_contract_version") != config.get(
|
|
599
|
+
"skill_contract_version"
|
|
600
|
+
):
|
|
601
|
+
raise SyncError("Skill contract version is incompatible with workflow")
|
|
602
|
+
controller_adapter = sources.compatibility.get(
|
|
603
|
+
"worktree_controller_adapter_version"
|
|
604
|
+
)
|
|
605
|
+
controller_status = sources.compatibility.get("worktree_controller_status")
|
|
606
|
+
if compatibility_version == 1:
|
|
607
|
+
if (
|
|
608
|
+
controller_adapter is not None
|
|
609
|
+
or controller_status != "planned_unavailable"
|
|
610
|
+
):
|
|
611
|
+
raise SyncError(
|
|
612
|
+
"v1 requires Worktree Controller contract to remain null/planned"
|
|
613
|
+
)
|
|
614
|
+
elif (
|
|
615
|
+
controller_adapter
|
|
616
|
+
!= (3 if compatibility_version >= 5 else 2 if compatibility_version >= 4 else 1)
|
|
617
|
+
or controller_status != "available_external"
|
|
618
|
+
):
|
|
619
|
+
raise SyncError(
|
|
620
|
+
"external Worktree Controller contract is incompatible with the toolchain"
|
|
621
|
+
)
|
|
622
|
+
except (OSError, UnicodeError, ValueError, KeyError, TypeError, SyncError) as exc:
|
|
623
|
+
errors.append(str(exc))
|
|
624
|
+
manifest = {}
|
|
625
|
+
contract_sha = None
|
|
626
|
+
skill_sha = None
|
|
627
|
+
|
|
628
|
+
return {
|
|
629
|
+
"tool": tool,
|
|
630
|
+
"status": "PASS" if not errors else "FAIL",
|
|
631
|
+
"canonical_commit": sources.head(tool),
|
|
632
|
+
"canonical_source_dirty": sources.dirty(tool),
|
|
633
|
+
"source_selection": "pinned_commit" if tool in sources.source_refs else "working_checkout",
|
|
634
|
+
"source_checkout_dirty": git_dirty(repo),
|
|
635
|
+
"canonical_tool_version": manifest.get("tool_version"),
|
|
636
|
+
"canonical_skill_sha256": skill_sha,
|
|
637
|
+
"public_cli_contract_sha256": contract_sha,
|
|
638
|
+
"errors": errors,
|
|
639
|
+
}
|
|
640
|
+
|
|
641
|
+
|
|
642
|
+
def extract_version(output: str) -> str | None:
|
|
643
|
+
matches = re.findall(r"(?<![0-9])([0-9]+\.[0-9]+\.[0-9]+)(?![0-9])", output)
|
|
644
|
+
return matches[-1] if matches else None
|
|
645
|
+
|
|
646
|
+
|
|
647
|
+
def bundled_sync_version(bundle: Path) -> str:
|
|
648
|
+
candidates = (
|
|
649
|
+
bundle / "executable" / "src" / "agent_toolchain" / "tool_skill_sync.py",
|
|
650
|
+
bundle / "executable" / "src" / "git_finalizer" / "toolchain" / "tool_skill_sync.py",
|
|
651
|
+
bundle / "executable" / "tooling" / "tool_skill_sync.py",
|
|
652
|
+
)
|
|
653
|
+
implementation = next((p for p in candidates if p.exists() or p.is_symlink()), candidates[0])
|
|
654
|
+
require_regular(implementation, "bundled tool-skill-sync implementation")
|
|
655
|
+
try:
|
|
656
|
+
tree = ast.parse(implementation.read_text(encoding="utf-8"), filename=str(implementation))
|
|
657
|
+
except (SyntaxError, UnicodeDecodeError) as exc:
|
|
658
|
+
raise SyncError(f"bundled tool-skill-sync implementation is unparseable: {exc}") from exc
|
|
659
|
+
versions: list[str] = []
|
|
660
|
+
for node in tree.body:
|
|
661
|
+
if isinstance(node, ast.Assign):
|
|
662
|
+
targets = [t.id for t in node.targets if isinstance(t, ast.Name)]
|
|
663
|
+
value = node.value
|
|
664
|
+
elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
|
|
665
|
+
targets = [node.target.id]
|
|
666
|
+
value = node.value
|
|
667
|
+
else:
|
|
668
|
+
continue
|
|
669
|
+
if (
|
|
670
|
+
"VERSION" in targets
|
|
671
|
+
and isinstance(value, ast.Constant)
|
|
672
|
+
and isinstance(value.value, str)
|
|
673
|
+
and VERSION_LITERAL_RE.fullmatch(value.value)
|
|
674
|
+
):
|
|
675
|
+
versions.append(value.value)
|
|
676
|
+
if len(versions) != 1:
|
|
677
|
+
raise SyncError("bundled tool-skill-sync VERSION constant is missing or ambiguous")
|
|
678
|
+
return versions[0]
|
|
679
|
+
|
|
680
|
+
|
|
681
|
+
def resolve_entry(name: str, bin_dir: Path | None) -> Path | None:
|
|
682
|
+
if bin_dir is not None:
|
|
683
|
+
candidate = bin_dir / name
|
|
684
|
+
return candidate.resolve() if candidate.exists() else None
|
|
685
|
+
resolved = shutil.which(name)
|
|
686
|
+
return Path(resolved).resolve() if resolved else None
|
|
687
|
+
|
|
688
|
+
|
|
689
|
+
def installed_binary_state(
|
|
690
|
+
entrypoints: Sequence[str], bin_dir: Path | None
|
|
691
|
+
) -> dict[str, Any]:
|
|
692
|
+
entries: dict[str, dict[str, str | None]] = {}
|
|
693
|
+
hashes: dict[str, str] = {}
|
|
694
|
+
versions: set[str] = set()
|
|
695
|
+
complete = True
|
|
696
|
+
for entrypoint in entrypoints:
|
|
697
|
+
path = resolve_entry(entrypoint, bin_dir)
|
|
698
|
+
if path is None or path.is_symlink() or not path.is_file():
|
|
699
|
+
entries[entrypoint] = {
|
|
700
|
+
"path": str(path) if path else None,
|
|
701
|
+
"sha256": None,
|
|
702
|
+
"version": None,
|
|
703
|
+
}
|
|
704
|
+
complete = False
|
|
705
|
+
continue
|
|
706
|
+
digest = sha256_file(path)
|
|
707
|
+
environment = os.environ.copy()
|
|
708
|
+
environment["PYTHONDONTWRITEBYTECODE"] = "1"
|
|
709
|
+
environment["GIT_OPTIONAL_LOCKS"] = "0"
|
|
710
|
+
result = run((str(path), "--version"), env=environment)
|
|
711
|
+
version = (
|
|
712
|
+
extract_version(result.stdout + "\n" + result.stderr)
|
|
713
|
+
if result.returncode == 0
|
|
714
|
+
else None
|
|
715
|
+
)
|
|
716
|
+
if version is None:
|
|
717
|
+
complete = False
|
|
718
|
+
else:
|
|
719
|
+
versions.add(version)
|
|
720
|
+
hashes[entrypoint] = digest
|
|
721
|
+
entries[entrypoint] = {"path": str(path), "sha256": digest, "version": version}
|
|
722
|
+
installed_version = (
|
|
723
|
+
next(iter(versions)) if complete and len(versions) == 1 else None
|
|
724
|
+
)
|
|
725
|
+
return {
|
|
726
|
+
"version": installed_version,
|
|
727
|
+
"sha256": aggregate_hash(hashes) if complete else None,
|
|
728
|
+
"entries": entries,
|
|
729
|
+
}
|
|
730
|
+
|
|
731
|
+
|
|
732
|
+
def check_tool_deployment(
|
|
733
|
+
sources: Sources,
|
|
734
|
+
tool: str,
|
|
735
|
+
agents_root: Path,
|
|
736
|
+
bin_dir: Path | None,
|
|
737
|
+
hooks_dir: Path | None = None,
|
|
738
|
+
) -> dict[str, Any]:
|
|
739
|
+
"""Validate the source contract and the installed production state together.
|
|
740
|
+
|
|
741
|
+
``source_contract_status`` keeps the original meaning: the canonical source repo is
|
|
742
|
+
internally consistent. ``installed_drift`` reports whether the executables actually on
|
|
743
|
+
PATH match the declared canonical release. ``status`` is PASS only when both hold, so
|
|
744
|
+
a stale or mismatched installation can no longer be reported as clean.
|
|
745
|
+
"""
|
|
746
|
+
checked = check_tool(sources, tool)
|
|
747
|
+
source_status = str(checked["status"])
|
|
748
|
+
installed_skill_sha, installed_compatibility_sha = installed_skill_hashes(
|
|
749
|
+
agents_root
|
|
750
|
+
)
|
|
751
|
+
errors = list(checked["errors"])
|
|
752
|
+
binary: dict[str, Any] = {"version": None, "sha256": None, "entries": {}}
|
|
753
|
+
drift = "unknown"
|
|
754
|
+
verification: dict[str, Any] = {}
|
|
755
|
+
try:
|
|
756
|
+
manifest = read_json(sources.manifest_path(tool))
|
|
757
|
+
entrypoints = validate_install_targets(manifest)
|
|
758
|
+
binary = installed_binary_state(entrypoints, bin_dir)
|
|
759
|
+
drift = classify_drift(
|
|
760
|
+
manifest,
|
|
761
|
+
source_status=source_status,
|
|
762
|
+
binary_version=binary["version"],
|
|
763
|
+
installed_skill_sha=installed_skill_sha,
|
|
764
|
+
installed_compatibility_sha=installed_compatibility_sha,
|
|
765
|
+
)
|
|
766
|
+
if drift != "none":
|
|
767
|
+
errors.append(
|
|
768
|
+
f"installed production state drifts from the canonical release: {drift}"
|
|
769
|
+
)
|
|
770
|
+
verification = verify_installed_tool_bytes(
|
|
771
|
+
sources, tool, manifest, entrypoints, bin_dir,
|
|
772
|
+
hooks_dir or agents_root / "hooks",
|
|
773
|
+
)
|
|
774
|
+
if verification.get("binary_content_drift"):
|
|
775
|
+
raise SyncError("installed executable/sidecar bytes differ from source")
|
|
776
|
+
except (OSError, ValueError, KeyError, SyncError) as exc:
|
|
777
|
+
errors.append(str(exc))
|
|
778
|
+
if drift == "none":
|
|
779
|
+
drift = "binary_only"
|
|
780
|
+
|
|
781
|
+
result = dict(checked)
|
|
782
|
+
result["source_contract_status"] = source_status
|
|
783
|
+
result["installed_binary_version"] = binary["version"]
|
|
784
|
+
result["installed_binary_sha256"] = binary["sha256"]
|
|
785
|
+
result["installed_binaries"] = binary["entries"]
|
|
786
|
+
result["installed_skill_sha256"] = installed_skill_sha
|
|
787
|
+
result["installed_compatibility_skill_sha256"] = installed_compatibility_sha
|
|
788
|
+
result["installed_drift"] = drift
|
|
789
|
+
result.update(verification)
|
|
790
|
+
result["errors"] = errors
|
|
791
|
+
result["status"] = "PASS" if not errors and source_status == "PASS" and drift == "none" else "FAIL"
|
|
792
|
+
return result
|
|
793
|
+
|
|
794
|
+
|
|
795
|
+
def verify_installed_tool_bytes(
|
|
796
|
+
sources: Sources, tool: str, manifest: dict[str, Any],
|
|
797
|
+
entrypoints: Sequence[str], bin_dir: Path | None, hooks_dir: Path,
|
|
798
|
+
) -> dict[str, Any]:
|
|
799
|
+
"""One read-only artifact check shared by check and doctor."""
|
|
800
|
+
executable = manifest["executable"]
|
|
801
|
+
if executable["kind"] == "python_console_scripts":
|
|
802
|
+
installation = python_tool_installation(entrypoints, bin_dir)
|
|
803
|
+
return {"artifact_verification": verify_installed_record(Path(installation["root"]))}
|
|
804
|
+
first = resolve_entry(entrypoints[0], bin_dir)
|
|
805
|
+
if first is None:
|
|
806
|
+
raise SyncError(f"entrypoint is missing: {entrypoints[0]}")
|
|
807
|
+
live_bin = bin_dir or first.parent
|
|
808
|
+
drift = []
|
|
809
|
+
for relative, target in executable["production_targets"].items():
|
|
810
|
+
parts = Path(target).parts
|
|
811
|
+
if parts[0] not in {"bin", "hooks"}:
|
|
812
|
+
raise SyncError(f"unsupported production target: {target}")
|
|
813
|
+
root = live_bin if parts[0] == "bin" else hooks_dir
|
|
814
|
+
live = root.joinpath(*parts[1:])
|
|
815
|
+
if not live.is_file() or sha256_file(live) != sha256_bytes(sources.source_bytes(tool, relative)):
|
|
816
|
+
drift.append(str(live))
|
|
817
|
+
return {"binary_content_drift": drift}
|
|
818
|
+
|
|
819
|
+
|
|
820
|
+
UV_EXECUTABLE = "uv"
|
|
821
|
+
|
|
822
|
+
|
|
823
|
+
def read_uv_receipt(root: Path) -> dict[str, Any]:
|
|
824
|
+
receipt = root / "uv-receipt.toml"
|
|
825
|
+
require_regular(receipt, "uv tool receipt")
|
|
826
|
+
with receipt.open("rb") as stream:
|
|
827
|
+
return tomllib.load(stream)
|
|
828
|
+
|
|
829
|
+
|
|
830
|
+
def python_tool_installation(
|
|
831
|
+
entrypoints: Sequence[str], bin_dir: Path | None
|
|
832
|
+
) -> dict[str, Any]:
|
|
833
|
+
"""Describe the uv tool installation that backs one tool's console scripts."""
|
|
834
|
+
resolved = {name: resolve_entry(name, bin_dir) for name in entrypoints}
|
|
835
|
+
missing = sorted(name for name, path in resolved.items() if path is None)
|
|
836
|
+
if missing:
|
|
837
|
+
raise SyncError(f"installed entrypoints are missing: {', '.join(missing)}")
|
|
838
|
+
# Retained legacy launchers deliberately live outside the uv tool directory and shim
|
|
839
|
+
# into it, so the uv root is the one directory that actually carries a uv receipt.
|
|
840
|
+
roots = set()
|
|
841
|
+
for path in resolved.values():
|
|
842
|
+
if path is None:
|
|
843
|
+
continue
|
|
844
|
+
for candidate in list(path.parents)[:3]:
|
|
845
|
+
if (candidate / "uv-receipt.toml").is_file():
|
|
846
|
+
roots.add(candidate)
|
|
847
|
+
break
|
|
848
|
+
if not roots:
|
|
849
|
+
raise SyncError(
|
|
850
|
+
"installed entrypoints do not resolve into a uv tool installation"
|
|
851
|
+
)
|
|
852
|
+
if len(roots) != 1:
|
|
853
|
+
raise SyncError("installed entrypoints resolve to more than one uv tool root")
|
|
854
|
+
root = roots.pop()
|
|
855
|
+
require_owned_directory(root)
|
|
856
|
+
receipt = read_uv_receipt(root)
|
|
857
|
+
tool_section = receipt.get("tool", {})
|
|
858
|
+
options = tool_section.get("options", {})
|
|
859
|
+
install_paths = {
|
|
860
|
+
entry["name"]: Path(entry["install-path"])
|
|
861
|
+
for entry in tool_section.get("entrypoints", [])
|
|
862
|
+
if isinstance(entry, dict) and "name" in entry and "install-path" in entry
|
|
863
|
+
}
|
|
864
|
+
if not set(entrypoints) <= set(install_paths):
|
|
865
|
+
raise SyncError("uv receipt does not cover every declared entrypoint")
|
|
866
|
+
directories = {path.parent for path in install_paths.values()}
|
|
867
|
+
if len(directories) != 1:
|
|
868
|
+
raise SyncError("uv receipt entrypoints span more than one bin directory")
|
|
869
|
+
indexes = [
|
|
870
|
+
item["url"]
|
|
871
|
+
for item in options.get("index", [])
|
|
872
|
+
if isinstance(item, dict) and isinstance(item.get("url"), str)
|
|
873
|
+
]
|
|
874
|
+
return {
|
|
875
|
+
"root": str(root),
|
|
876
|
+
"bin_dir": str(directories.pop()),
|
|
877
|
+
"indexes": indexes,
|
|
878
|
+
"no_build": bool(options.get("no-build", False)),
|
|
879
|
+
"entry_targets": {
|
|
880
|
+
name: str(path) for name, path in sorted(install_paths.items())
|
|
881
|
+
},
|
|
882
|
+
"resolved": {
|
|
883
|
+
name: str(path)
|
|
884
|
+
for name, path in sorted(resolved.items())
|
|
885
|
+
if path is not None
|
|
886
|
+
},
|
|
887
|
+
}
|
|
888
|
+
|
|
889
|
+
|
|
890
|
+
def verify_installed_record(root: Path) -> dict[str, Any]:
|
|
891
|
+
"""Verify installed runtime files against the published wheel RECORD."""
|
|
892
|
+
candidates = sorted(root.glob("lib/python*/site-packages"))
|
|
893
|
+
if len(candidates) != 1:
|
|
894
|
+
raise SyncError("uv tool installation has no single site-packages directory")
|
|
895
|
+
site_packages = candidates[0]
|
|
896
|
+
dist_infos = sorted(site_packages.glob("*.dist-info"))
|
|
897
|
+
if not dist_infos:
|
|
898
|
+
raise SyncError("uv tool installation has no dist-info directory")
|
|
899
|
+
verified = 0
|
|
900
|
+
for dist_info in dist_infos:
|
|
901
|
+
record = dist_info / "RECORD"
|
|
902
|
+
require_regular(record, "installed RECORD")
|
|
903
|
+
distribution_verified = 0
|
|
904
|
+
for line in record.read_text(encoding="utf-8").splitlines():
|
|
905
|
+
if not line:
|
|
906
|
+
continue
|
|
907
|
+
name, _, remainder = line.partition(",")
|
|
908
|
+
digest, _, _size = remainder.partition(",")
|
|
909
|
+
# Console scripts live outside site-packages and RECORD lists itself without a hash.
|
|
910
|
+
if not digest.startswith("sha256=") or name.startswith("../"):
|
|
911
|
+
continue
|
|
912
|
+
target = site_packages / name
|
|
913
|
+
if not target.is_file():
|
|
914
|
+
raise SyncError(f"installed file is missing: {name}")
|
|
915
|
+
expected = digest.split("=", 1)[1]
|
|
916
|
+
actual = (
|
|
917
|
+
base64.urlsafe_b64encode(hashlib.sha256(target.read_bytes()).digest())
|
|
918
|
+
.rstrip(b"=")
|
|
919
|
+
.decode()
|
|
920
|
+
)
|
|
921
|
+
if actual != expected:
|
|
922
|
+
raise SyncError(
|
|
923
|
+
f"installed file does not match the published artifact: {name}"
|
|
924
|
+
)
|
|
925
|
+
distribution_verified += 1
|
|
926
|
+
if not distribution_verified:
|
|
927
|
+
raise SyncError(f"installed RECORD verified no files: {dist_info.name}")
|
|
928
|
+
verified += distribution_verified
|
|
929
|
+
if len(dist_infos) == 1:
|
|
930
|
+
return {"dist_info": dist_infos[0].name, "verified_files": verified}
|
|
931
|
+
return {"dist_infos": [path.name for path in dist_infos], "verified_files": verified}
|
|
932
|
+
|
|
933
|
+
|
|
934
|
+
def install_python_tool(
|
|
935
|
+
tool: str,
|
|
936
|
+
version: str,
|
|
937
|
+
*,
|
|
938
|
+
bin_dir: str,
|
|
939
|
+
indexes: Sequence[str],
|
|
940
|
+
no_build: bool,
|
|
941
|
+
) -> None:
|
|
942
|
+
"""Install one pinned uv tool release, preserving the recorded installation shape.
|
|
943
|
+
|
|
944
|
+
``--force`` is required: ``--reinstall`` removes the existing installation before it
|
|
945
|
+
validates entrypoint conflicts, which can leave production with no working CLI.
|
|
946
|
+
"""
|
|
947
|
+
argv = [UV_EXECUTABLE, "tool", "install", "--force"]
|
|
948
|
+
if no_build:
|
|
949
|
+
argv.append("--no-build")
|
|
950
|
+
for index in indexes:
|
|
951
|
+
argv.extend(("--index", index))
|
|
952
|
+
argv.append(f"{tool}=={version}")
|
|
953
|
+
environment = dict(os.environ, UV_TOOL_BIN_DIR=bin_dir)
|
|
954
|
+
result = subprocess.run(
|
|
955
|
+
argv, capture_output=True, text=True, check=False, env=environment
|
|
956
|
+
)
|
|
957
|
+
if result.returncode:
|
|
958
|
+
raise SyncError(
|
|
959
|
+
f"uv tool install failed for {tool}=={version} "
|
|
960
|
+
f"(exit {result.returncode}): {result.stderr.strip()[:200]}"
|
|
961
|
+
)
|
|
962
|
+
|
|
963
|
+
|
|
964
|
+
def install_local_python_tool(
|
|
965
|
+
tool: str,
|
|
966
|
+
source_path: Path,
|
|
967
|
+
*,
|
|
968
|
+
bin_dir: str,
|
|
969
|
+
no_build: bool,
|
|
970
|
+
) -> None:
|
|
971
|
+
"""Install one tool offline from a verified local checkout or exported commit tree."""
|
|
972
|
+
argv = [UV_EXECUTABLE, "tool", "install", "--force", "--offline"]
|
|
973
|
+
if no_build:
|
|
974
|
+
argv.append("--no-build")
|
|
975
|
+
argv.append(os.fspath(source_path))
|
|
976
|
+
environment = dict(os.environ, UV_TOOL_BIN_DIR=bin_dir)
|
|
977
|
+
result = subprocess.run(
|
|
978
|
+
argv, capture_output=True, text=True, check=False, env=environment
|
|
979
|
+
)
|
|
980
|
+
if result.returncode:
|
|
981
|
+
raise SyncError(
|
|
982
|
+
f"uv tool offline install failed for {tool} "
|
|
983
|
+
f"(exit {result.returncode}): {result.stderr.strip()[:200]}"
|
|
984
|
+
)
|
|
985
|
+
|
|
986
|
+
|
|
987
|
+
def _resolves_into_python_venv(entry: Path) -> bool:
|
|
988
|
+
resolved = entry.resolve(strict=False)
|
|
989
|
+
return any((parent / "pyvenv.cfg").is_file() for parent in list(resolved.parents)[:3])
|
|
990
|
+
|
|
991
|
+
|
|
992
|
+
def _legacy_source_files_installation(
|
|
993
|
+
entrypoints: Sequence[str], bin_dir: Path | None
|
|
994
|
+
) -> dict[str, Any] | None:
|
|
995
|
+
"""Describe a legacy `source_files` install so 1.x -> 2.x wheel upgrade works cleanly."""
|
|
996
|
+
targets: dict[str, Path] = {}
|
|
997
|
+
dirs: set[Path] = set()
|
|
998
|
+
for name in entrypoints:
|
|
999
|
+
if bin_dir is not None:
|
|
1000
|
+
candidate = bin_dir / name
|
|
1001
|
+
else:
|
|
1002
|
+
found = shutil.which(name)
|
|
1003
|
+
if not found:
|
|
1004
|
+
return None
|
|
1005
|
+
candidate = Path(found)
|
|
1006
|
+
if not candidate.exists() or _resolves_into_python_venv(candidate):
|
|
1007
|
+
return None
|
|
1008
|
+
targets[name] = candidate
|
|
1009
|
+
dirs.add(candidate.parent.resolve())
|
|
1010
|
+
if len(dirs) != 1:
|
|
1011
|
+
return None
|
|
1012
|
+
target_bin = dirs.pop()
|
|
1013
|
+
return {
|
|
1014
|
+
"root": None,
|
|
1015
|
+
"bin_dir": str(target_bin),
|
|
1016
|
+
"indexes": [],
|
|
1017
|
+
"no_build": False,
|
|
1018
|
+
"entry_targets": {},
|
|
1019
|
+
"resolved": {},
|
|
1020
|
+
"legacy_targets": {name: str(path) for name, path in sorted(targets.items())},
|
|
1021
|
+
"legacy_source_files": True,
|
|
1022
|
+
}
|
|
1023
|
+
|
|
1024
|
+
|
|
1025
|
+
def _backup_legacy_entries(entry_map: dict[str, str]) -> dict[Path, dict[str, Any]]:
|
|
1026
|
+
snapshot: dict[Path, dict[str, Any]] = {}
|
|
1027
|
+
for raw_path in entry_map.values():
|
|
1028
|
+
path = Path(raw_path)
|
|
1029
|
+
if path.is_symlink():
|
|
1030
|
+
snapshot[path] = {"symlink": os.readlink(path)}
|
|
1031
|
+
elif path.is_file():
|
|
1032
|
+
snapshot[path] = {
|
|
1033
|
+
"bytes": path.read_bytes(),
|
|
1034
|
+
"mode": stat.S_IMODE(path.stat().st_mode),
|
|
1035
|
+
}
|
|
1036
|
+
return snapshot
|
|
1037
|
+
|
|
1038
|
+
|
|
1039
|
+
def _restore_legacy_entries(snapshot: dict[Path, dict[str, Any]]) -> None:
|
|
1040
|
+
for path, info in snapshot.items():
|
|
1041
|
+
if "symlink" in info:
|
|
1042
|
+
atomic_symlink(path.parent, path.name, Path(info["symlink"]))
|
|
1043
|
+
continue
|
|
1044
|
+
fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.restore-")
|
|
1045
|
+
os.close(fd)
|
|
1046
|
+
tmp = Path(tmp_name)
|
|
1047
|
+
try:
|
|
1048
|
+
tmp.write_bytes(info["bytes"])
|
|
1049
|
+
tmp.chmod(info["mode"])
|
|
1050
|
+
os.replace(tmp, path)
|
|
1051
|
+
fsync_directory(path.parent)
|
|
1052
|
+
finally:
|
|
1053
|
+
if tmp.exists():
|
|
1054
|
+
tmp.unlink()
|
|
1055
|
+
|
|
1056
|
+
|
|
1057
|
+
@contextmanager
|
|
1058
|
+
def _local_install_source(sources: Sources, tool: str):
|
|
1059
|
+
repo = sources.repo(tool)
|
|
1060
|
+
if tool not in sources.source_refs:
|
|
1061
|
+
yield repo
|
|
1062
|
+
return
|
|
1063
|
+
oid = sources.source_refs[tool]
|
|
1064
|
+
if not FULL_GIT_OID.fullmatch(oid):
|
|
1065
|
+
raise SyncError("source-ref requires a full commit OID")
|
|
1066
|
+
with tempfile.TemporaryDirectory(prefix=f".{tool}-src-") as staging:
|
|
1067
|
+
archive = subprocess.run(
|
|
1068
|
+
["git", "-C", str(repo), "archive", "--format=tar", oid],
|
|
1069
|
+
capture_output=True,
|
|
1070
|
+
check=False,
|
|
1071
|
+
timeout=30,
|
|
1072
|
+
)
|
|
1073
|
+
if archive.returncode:
|
|
1074
|
+
raise SyncError(f"git archive failed for pinned {tool}@{oid}")
|
|
1075
|
+
target_dir = Path(staging) / tool
|
|
1076
|
+
target_dir.mkdir(mode=0o700)
|
|
1077
|
+
with tarfile.open(fileobj=io.BytesIO(archive.stdout), mode="r:*") as tf:
|
|
1078
|
+
tf.extractall(target_dir, filter="data")
|
|
1079
|
+
yield target_dir
|
|
1080
|
+
|
|
1081
|
+
|
|
1082
|
+
def canonical_install_policy(
|
|
1083
|
+
sources: Sources, tool: str, observed: dict[str, Any]
|
|
1084
|
+
) -> tuple[dict[str, Any], bool]:
|
|
1085
|
+
"""Return the intended uv install shape and whether the observed receipt drifted.
|
|
1086
|
+
|
|
1087
|
+
``uv_install_policy`` in the toolchain compatibility contract is authoritative when
|
|
1088
|
+
present, so a receipt that drifted away from the declared bin directory, package index
|
|
1089
|
+
or no-build policy is normalized instead of being preserved. Without a declared policy
|
|
1090
|
+
the observed receipt is kept, which is the previous behavior.
|
|
1091
|
+
"""
|
|
1092
|
+
policy = sources.tool_config.get(tool, {}).get("uv_install_policy")
|
|
1093
|
+
if policy is None:
|
|
1094
|
+
return dict(observed), False
|
|
1095
|
+
if not isinstance(policy, dict):
|
|
1096
|
+
raise SyncError(f"{tool} uv_install_policy must be an object")
|
|
1097
|
+
bin_dir = policy.get("bin_dir")
|
|
1098
|
+
if not isinstance(bin_dir, str) or not bin_dir:
|
|
1099
|
+
raise SyncError(f"{tool} uv_install_policy bin_dir is invalid")
|
|
1100
|
+
resolved = Path(bin_dir).expanduser()
|
|
1101
|
+
if not resolved.is_absolute():
|
|
1102
|
+
raise SyncError(
|
|
1103
|
+
f"{tool} uv_install_policy bin_dir must resolve to an absolute path"
|
|
1104
|
+
)
|
|
1105
|
+
indexes = policy.get("index", [])
|
|
1106
|
+
if not isinstance(indexes, list) or not all(
|
|
1107
|
+
isinstance(item, str) and item for item in indexes
|
|
1108
|
+
):
|
|
1109
|
+
raise SyncError(f"{tool} uv_install_policy index must be a list of URLs")
|
|
1110
|
+
intended = dict(observed)
|
|
1111
|
+
intended["bin_dir"] = os.fspath(resolved)
|
|
1112
|
+
intended["indexes"] = list(indexes)
|
|
1113
|
+
intended["no_build"] = bool(policy.get("no_build", False))
|
|
1114
|
+
drifted = (
|
|
1115
|
+
observed["bin_dir"] != intended["bin_dir"]
|
|
1116
|
+
or observed["no_build"] != intended["no_build"]
|
|
1117
|
+
or not set(intended["indexes"]) <= set(observed["indexes"])
|
|
1118
|
+
)
|
|
1119
|
+
return intended, drifted
|
|
1120
|
+
|
|
1121
|
+
|
|
1122
|
+
def verify_python_tool(
|
|
1123
|
+
tool: str,
|
|
1124
|
+
version: str,
|
|
1125
|
+
entrypoints: Sequence[str],
|
|
1126
|
+
bin_dir: Path | None,
|
|
1127
|
+
expected: dict[str, Any],
|
|
1128
|
+
*,
|
|
1129
|
+
expect_stable_paths: bool = True,
|
|
1130
|
+
) -> dict[str, Any]:
|
|
1131
|
+
"""Fail closed unless every entrypoint, hash and receipt field matches the release."""
|
|
1132
|
+
binary = installed_binary_state(entrypoints, bin_dir)
|
|
1133
|
+
if binary["version"] != version:
|
|
1134
|
+
raise SyncError(
|
|
1135
|
+
f"installed {tool} reports {binary['version']}, expected {version}"
|
|
1136
|
+
)
|
|
1137
|
+
installation = python_tool_installation(entrypoints, bin_dir)
|
|
1138
|
+
if installation["bin_dir"] != expected["bin_dir"]:
|
|
1139
|
+
raise SyncError("upgrade changed the entrypoint bin directory")
|
|
1140
|
+
if installation["no_build"] != expected["no_build"]:
|
|
1141
|
+
raise SyncError("upgrade changed the receipt no-build setting")
|
|
1142
|
+
if not set(expected["indexes"]) <= set(installation["indexes"]):
|
|
1143
|
+
raise SyncError("upgrade dropped a recorded package index")
|
|
1144
|
+
# A release may intentionally remove console scripts, so compare only the entrypoints
|
|
1145
|
+
# the target release declares. Retained entrypoints must keep their exact install path
|
|
1146
|
+
# and resolved target; entrypoints the new release drops are reported as retired.
|
|
1147
|
+
for name in entrypoints if expect_stable_paths else ():
|
|
1148
|
+
previous_target = expected["entry_targets"].get(name)
|
|
1149
|
+
if (
|
|
1150
|
+
previous_target is not None
|
|
1151
|
+
and installation["entry_targets"][name] != previous_target
|
|
1152
|
+
):
|
|
1153
|
+
raise SyncError(f"upgrade changed the install path of {name}")
|
|
1154
|
+
previous_resolved = expected["resolved"].get(name)
|
|
1155
|
+
if (
|
|
1156
|
+
previous_resolved is not None
|
|
1157
|
+
and installation["resolved"][name] != previous_resolved
|
|
1158
|
+
):
|
|
1159
|
+
raise SyncError(f"upgrade changed the resolved target of {name}")
|
|
1160
|
+
retired = sorted(set(expected["entry_targets"]) - set(entrypoints))
|
|
1161
|
+
for name in retired:
|
|
1162
|
+
path = Path(expected["entry_targets"][name])
|
|
1163
|
+
if path.exists() or path.is_symlink():
|
|
1164
|
+
raise SyncError(f"upgrade left a retired entrypoint installed: {name}")
|
|
1165
|
+
record = verify_installed_record(Path(installation["root"]))
|
|
1166
|
+
return {
|
|
1167
|
+
"version": binary["version"],
|
|
1168
|
+
"binary_sha256": binary["sha256"],
|
|
1169
|
+
"entries": binary["entries"],
|
|
1170
|
+
"installation": installation,
|
|
1171
|
+
"retired_entrypoints": retired,
|
|
1172
|
+
"record": record,
|
|
1173
|
+
}
|
|
1174
|
+
|
|
1175
|
+
|
|
1176
|
+
def upgrade(
|
|
1177
|
+
sources: Sources,
|
|
1178
|
+
tool: str,
|
|
1179
|
+
*,
|
|
1180
|
+
bin_dir: Path | None,
|
|
1181
|
+
dry_run: bool = False,
|
|
1182
|
+
previous_bundle: Path | None = None,
|
|
1183
|
+
) -> dict[str, Any]:
|
|
1184
|
+
"""Upgrade one console-script tool to its canonical release, or restore the old one."""
|
|
1185
|
+
checked = check_tool(sources, tool)
|
|
1186
|
+
if checked["status"] != "PASS":
|
|
1187
|
+
raise SyncError("canonical check failed: " + "; ".join(checked["errors"]))
|
|
1188
|
+
manifest = read_json(sources.manifest_path(tool))
|
|
1189
|
+
entrypoints = validate_install_targets(manifest)
|
|
1190
|
+
if manifest["executable"]["kind"] != "python_console_scripts":
|
|
1191
|
+
raise SyncError(f"{tool} is not installed as Python console scripts")
|
|
1192
|
+
target_version = str(manifest["tool_version"])
|
|
1193
|
+
previous_entries = entrypoints
|
|
1194
|
+
previous_manifest = None
|
|
1195
|
+
if previous_bundle is not None:
|
|
1196
|
+
verify_bundle(previous_bundle, tool)
|
|
1197
|
+
previous_manifest = read_json(previous_bundle / "tool_skill_manifest.json")
|
|
1198
|
+
if previous_manifest["executable"]["kind"] not in {"python_console_scripts", "source_files"}:
|
|
1199
|
+
raise SyncError("previous bundle is not a supported executable kind")
|
|
1200
|
+
previous_entries = validate_install_targets(previous_manifest, allow_legacy=True)
|
|
1201
|
+
if previous_manifest is not None and previous_manifest["executable"]["kind"] == "source_files":
|
|
1202
|
+
before = _legacy_source_files_installation(previous_entries, bin_dir)
|
|
1203
|
+
if before is None:
|
|
1204
|
+
raise SyncError("legacy source_files installation is incomplete or unavailable")
|
|
1205
|
+
else:
|
|
1206
|
+
try:
|
|
1207
|
+
before = python_tool_installation(previous_entries, bin_dir)
|
|
1208
|
+
except SyncError:
|
|
1209
|
+
legacy = (
|
|
1210
|
+
_legacy_source_files_installation(previous_entries, bin_dir)
|
|
1211
|
+
if previous_manifest is None
|
|
1212
|
+
else None
|
|
1213
|
+
)
|
|
1214
|
+
if legacy is None:
|
|
1215
|
+
raise
|
|
1216
|
+
before = legacy
|
|
1217
|
+
intended, drifted = canonical_install_policy(sources, tool, before)
|
|
1218
|
+
legacy_upgrade = bool(before.get("legacy_source_files"))
|
|
1219
|
+
previous_version = installed_binary_state(previous_entries, bin_dir)["version"]
|
|
1220
|
+
if previous_manifest is not None:
|
|
1221
|
+
if previous_version != previous_manifest["tool_version"]:
|
|
1222
|
+
raise SyncError("installed release does not match the explicit previous bundle")
|
|
1223
|
+
if not legacy_upgrade:
|
|
1224
|
+
verify_python_tool(tool, previous_version, previous_entries, bin_dir, before)
|
|
1225
|
+
stable_paths = intended["bin_dir"] == before["bin_dir"] and not legacy_upgrade
|
|
1226
|
+
plan = {
|
|
1227
|
+
"schema_version": SCHEMA_VERSION,
|
|
1228
|
+
"operation": "upgrade",
|
|
1229
|
+
"tool": tool,
|
|
1230
|
+
"previous_version": previous_version,
|
|
1231
|
+
"target_version": target_version,
|
|
1232
|
+
"bin_dir": intended["bin_dir"],
|
|
1233
|
+
"indexes": intended["indexes"],
|
|
1234
|
+
"no_build": intended["no_build"],
|
|
1235
|
+
"receipt_drifted": drifted,
|
|
1236
|
+
"observed_bin_dir": before["bin_dir"],
|
|
1237
|
+
"observed_no_build": before["no_build"],
|
|
1238
|
+
}
|
|
1239
|
+
if (
|
|
1240
|
+
not legacy_upgrade
|
|
1241
|
+
and previous_version == target_version
|
|
1242
|
+
and not drifted
|
|
1243
|
+
and previous_entries == entrypoints
|
|
1244
|
+
):
|
|
1245
|
+
plan["status"] = "UNCHANGED"
|
|
1246
|
+
plan["verification"] = verify_python_tool(
|
|
1247
|
+
tool, target_version, entrypoints, bin_dir, intended
|
|
1248
|
+
)
|
|
1249
|
+
return plan
|
|
1250
|
+
if dry_run:
|
|
1251
|
+
plan["status"] = "DRY_RUN_NORMALIZE" if drifted else "DRY_RUN"
|
|
1252
|
+
return plan
|
|
1253
|
+
legacy_backup = (
|
|
1254
|
+
_backup_legacy_entries(before.get("legacy_targets", {})) if legacy_upgrade else None
|
|
1255
|
+
)
|
|
1256
|
+
try:
|
|
1257
|
+
if intended["indexes"]:
|
|
1258
|
+
install_python_tool(
|
|
1259
|
+
tool,
|
|
1260
|
+
target_version,
|
|
1261
|
+
bin_dir=intended["bin_dir"],
|
|
1262
|
+
indexes=intended["indexes"],
|
|
1263
|
+
no_build=intended["no_build"],
|
|
1264
|
+
)
|
|
1265
|
+
else:
|
|
1266
|
+
with _local_install_source(sources, tool) as local_source:
|
|
1267
|
+
install_local_python_tool(
|
|
1268
|
+
tool,
|
|
1269
|
+
local_source,
|
|
1270
|
+
bin_dir=intended["bin_dir"],
|
|
1271
|
+
no_build=intended["no_build"],
|
|
1272
|
+
)
|
|
1273
|
+
plan["verification"] = verify_python_tool(
|
|
1274
|
+
tool,
|
|
1275
|
+
target_version,
|
|
1276
|
+
entrypoints,
|
|
1277
|
+
bin_dir,
|
|
1278
|
+
intended,
|
|
1279
|
+
expect_stable_paths=stable_paths,
|
|
1280
|
+
)
|
|
1281
|
+
except (SyncError, OSError, subprocess.SubprocessError, KeyboardInterrupt) as exc:
|
|
1282
|
+
plan["status"] = "RESTORED"
|
|
1283
|
+
plan["error"] = str(exc)
|
|
1284
|
+
if legacy_backup is not None:
|
|
1285
|
+
try:
|
|
1286
|
+
_restore_legacy_entries(legacy_backup)
|
|
1287
|
+
plan["restored_shape"] = "legacy_source_files"
|
|
1288
|
+
except (SyncError, OSError, subprocess.SubprocessError) as restore_error:
|
|
1289
|
+
plan["status"] = "FAILED"
|
|
1290
|
+
raise SyncError(
|
|
1291
|
+
f"{exc}; restoring legacy {previous_version} also failed: {restore_error}"
|
|
1292
|
+
) from None
|
|
1293
|
+
if isinstance(exc, KeyboardInterrupt):
|
|
1294
|
+
raise
|
|
1295
|
+
raise SyncError(
|
|
1296
|
+
f"upgrade failed and legacy {previous_version} was restored: {exc}"
|
|
1297
|
+
) from None
|
|
1298
|
+
if previous_version is None:
|
|
1299
|
+
plan["status"] = "FAILED"
|
|
1300
|
+
raise SyncError(f"{exc}; no previous version recorded to restore") from None
|
|
1301
|
+
try:
|
|
1302
|
+
install_python_tool(
|
|
1303
|
+
tool,
|
|
1304
|
+
previous_version,
|
|
1305
|
+
bin_dir=before["bin_dir"],
|
|
1306
|
+
indexes=before["indexes"],
|
|
1307
|
+
no_build=before["no_build"],
|
|
1308
|
+
)
|
|
1309
|
+
plan["restored_verification"] = verify_python_tool(
|
|
1310
|
+
tool, previous_version, previous_entries, bin_dir, before
|
|
1311
|
+
)
|
|
1312
|
+
for name in set(entrypoints) - set(previous_entries):
|
|
1313
|
+
path = Path(intended["bin_dir"]) / name
|
|
1314
|
+
if path.exists() or path.is_symlink():
|
|
1315
|
+
raise SyncError(f"restoration left a new entrypoint installed: {name}")
|
|
1316
|
+
plan["restored_shape"] = "observed"
|
|
1317
|
+
except (SyncError, OSError, subprocess.SubprocessError) as restore_error:
|
|
1318
|
+
plan["status"] = "FAILED"
|
|
1319
|
+
raise SyncError(
|
|
1320
|
+
f"{exc}; restoring {previous_version} also failed: {restore_error}"
|
|
1321
|
+
) from None
|
|
1322
|
+
if isinstance(exc, KeyboardInterrupt):
|
|
1323
|
+
raise
|
|
1324
|
+
raise SyncError(
|
|
1325
|
+
f"upgrade failed and {previous_version} was restored: {exc}"
|
|
1326
|
+
) from None
|
|
1327
|
+
plan["status"] = (
|
|
1328
|
+
"NORMALIZED" if (not legacy_upgrade and previous_version == target_version) else "UPGRADED"
|
|
1329
|
+
)
|
|
1330
|
+
return plan
|
|
1331
|
+
|
|
1332
|
+
|
|
1333
|
+
def installed_skill_hashes(agents_root: Path) -> tuple[str | None, str | None]:
|
|
1334
|
+
"""Return the installed canonical and compatibility Skill payload hashes."""
|
|
1335
|
+
try:
|
|
1336
|
+
skill_sha = tree_sha256(agents_root / "skills" / SKILL_NAME, SKILL_PAYLOAD)
|
|
1337
|
+
except SyncError:
|
|
1338
|
+
skill_sha = None
|
|
1339
|
+
compatibility = agents_root / "skills" / COMPATIBILITY_SKILL_NAME / "SKILL.md"
|
|
1340
|
+
try:
|
|
1341
|
+
require_regular(compatibility, "installed compatibility Skill")
|
|
1342
|
+
compatibility_sha = sha256_file(compatibility)
|
|
1343
|
+
except SyncError:
|
|
1344
|
+
compatibility_sha = None
|
|
1345
|
+
return skill_sha, compatibility_sha
|
|
1346
|
+
|
|
1347
|
+
|
|
1348
|
+
def classify_drift(
|
|
1349
|
+
manifest: dict[str, Any],
|
|
1350
|
+
*,
|
|
1351
|
+
source_status: str,
|
|
1352
|
+
binary_version: str | None,
|
|
1353
|
+
installed_skill_sha: str | None,
|
|
1354
|
+
installed_compatibility_sha: str | None,
|
|
1355
|
+
) -> str:
|
|
1356
|
+
"""Classify installed production state against the declared canonical release."""
|
|
1357
|
+
binary_matches = binary_version == manifest.get("tool_version")
|
|
1358
|
+
skill_matches = installed_skill_sha == manifest.get(
|
|
1359
|
+
"canonical_skill_sha256"
|
|
1360
|
+
) and installed_compatibility_sha == manifest.get("compatibility_skill", {}).get(
|
|
1361
|
+
"sha256"
|
|
1362
|
+
)
|
|
1363
|
+
if source_status != "PASS" or (not binary_matches and not skill_matches):
|
|
1364
|
+
return "incompatible"
|
|
1365
|
+
if binary_matches and skill_matches:
|
|
1366
|
+
return "none"
|
|
1367
|
+
if binary_matches:
|
|
1368
|
+
return "skill_only"
|
|
1369
|
+
return "binary_only"
|
|
1370
|
+
|
|
1371
|
+
|
|
1372
|
+
def status(sources: Sources, agents_root: Path, bin_dir: Path | None) -> dict[str, Any]:
|
|
1373
|
+
result: dict[str, Any] = {
|
|
1374
|
+
"schema_version": SCHEMA_VERSION,
|
|
1375
|
+
"operation": "status",
|
|
1376
|
+
"tools": [],
|
|
1377
|
+
}
|
|
1378
|
+
installed_skill_sha, installed_compatibility_sha = installed_skill_hashes(
|
|
1379
|
+
agents_root
|
|
1380
|
+
)
|
|
1381
|
+
|
|
1382
|
+
for tool in sources.names():
|
|
1383
|
+
checked = check_tool(sources, tool)
|
|
1384
|
+
try:
|
|
1385
|
+
manifest = read_json(sources.manifest_path(tool))
|
|
1386
|
+
entrypoints = validate_install_targets(manifest)
|
|
1387
|
+
except SyncError:
|
|
1388
|
+
result["tools"].append(
|
|
1389
|
+
{
|
|
1390
|
+
"tool_name": tool,
|
|
1391
|
+
"canonical_tool_version": checked["canonical_tool_version"],
|
|
1392
|
+
"canonical_commit": checked["canonical_commit"],
|
|
1393
|
+
"canonical_source_dirty": checked["canonical_source_dirty"],
|
|
1394
|
+
"canonical_skill_sha256": checked["canonical_skill_sha256"],
|
|
1395
|
+
"public_cli_contract_sha256": checked["public_cli_contract_sha256"],
|
|
1396
|
+
"installed_binary_version": None,
|
|
1397
|
+
"installed_binary_sha256": None,
|
|
1398
|
+
"installed_binaries": {},
|
|
1399
|
+
"installed_skill_sha256": installed_skill_sha,
|
|
1400
|
+
"installed_compatibility_skill_sha256": (
|
|
1401
|
+
installed_compatibility_sha
|
|
1402
|
+
),
|
|
1403
|
+
"drift": "incompatible",
|
|
1404
|
+
}
|
|
1405
|
+
)
|
|
1406
|
+
continue
|
|
1407
|
+
binary = installed_binary_state(entrypoints, bin_dir)
|
|
1408
|
+
drift = classify_drift(
|
|
1409
|
+
manifest,
|
|
1410
|
+
source_status=str(checked["status"]),
|
|
1411
|
+
binary_version=binary["version"],
|
|
1412
|
+
installed_skill_sha=installed_skill_sha,
|
|
1413
|
+
installed_compatibility_sha=installed_compatibility_sha,
|
|
1414
|
+
)
|
|
1415
|
+
result["tools"].append(
|
|
1416
|
+
{
|
|
1417
|
+
"tool_name": tool,
|
|
1418
|
+
"canonical_tool_version": manifest.get("tool_version"),
|
|
1419
|
+
"canonical_commit": sources.head(tool),
|
|
1420
|
+
"canonical_source_dirty": sources.dirty(tool),
|
|
1421
|
+
"canonical_skill_sha256": manifest.get("canonical_skill_sha256"),
|
|
1422
|
+
"public_cli_contract_sha256": manifest.get(
|
|
1423
|
+
"public_cli_contract_sha256"
|
|
1424
|
+
),
|
|
1425
|
+
"installed_binary_version": binary["version"],
|
|
1426
|
+
"installed_binary_sha256": binary["sha256"],
|
|
1427
|
+
"installed_binaries": binary["entries"],
|
|
1428
|
+
"installed_skill_sha256": installed_skill_sha,
|
|
1429
|
+
"installed_compatibility_skill_sha256": installed_compatibility_sha,
|
|
1430
|
+
"drift": drift,
|
|
1431
|
+
}
|
|
1432
|
+
)
|
|
1433
|
+
return result
|
|
1434
|
+
|
|
1435
|
+
|
|
1436
|
+
def copy_skill_payload(source: Path, target: Path) -> None:
|
|
1437
|
+
for relative in SKILL_PAYLOAD:
|
|
1438
|
+
source_path = source / relative
|
|
1439
|
+
target_path = target / relative
|
|
1440
|
+
target_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
|
|
1441
|
+
shutil.copyfile(source_path, target_path)
|
|
1442
|
+
target_path.chmod(0o600)
|
|
1443
|
+
|
|
1444
|
+
|
|
1445
|
+
def copy_compatibility_skill(source: Path, target: Path) -> None:
|
|
1446
|
+
source_path = source / "SKILL.md"
|
|
1447
|
+
require_regular(source_path, "compatibility Skill source")
|
|
1448
|
+
target_path = target / COMPATIBILITY_BUNDLE_PATH
|
|
1449
|
+
target_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
|
|
1450
|
+
shutil.copyfile(source_path, target_path)
|
|
1451
|
+
target_path.chmod(0o600)
|
|
1452
|
+
|
|
1453
|
+
|
|
1454
|
+
def source_executable_payload(
|
|
1455
|
+
repo: Path,
|
|
1456
|
+
manifest: dict[str, Any],
|
|
1457
|
+
target: Path,
|
|
1458
|
+
tool_commit: str,
|
|
1459
|
+
) -> tuple[str, dict[str, str]]:
|
|
1460
|
+
executable = manifest["executable"]
|
|
1461
|
+
kind = executable["kind"]
|
|
1462
|
+
if kind == "python_console_scripts":
|
|
1463
|
+
identity = {
|
|
1464
|
+
"schema_version": SCHEMA_VERSION,
|
|
1465
|
+
"kind": kind,
|
|
1466
|
+
"tool_name": manifest["tool_name"],
|
|
1467
|
+
"tool_version": manifest["tool_version"],
|
|
1468
|
+
"tool_commit": tool_commit,
|
|
1469
|
+
"entrypoints": executable["entrypoints"],
|
|
1470
|
+
}
|
|
1471
|
+
identity_path = target / "executable_identity.json"
|
|
1472
|
+
write_json(identity_path, identity)
|
|
1473
|
+
digest = sha256_file(identity_path)
|
|
1474
|
+
return digest, {"executable_identity.json": digest}
|
|
1475
|
+
|
|
1476
|
+
executable_root = target / "executable"
|
|
1477
|
+
executable_root.mkdir(mode=0o700)
|
|
1478
|
+
hashes: dict[str, str] = {}
|
|
1479
|
+
for relative in executable["paths"]:
|
|
1480
|
+
source_path = repo / relative
|
|
1481
|
+
require_regular(source_path, "executable source")
|
|
1482
|
+
target_path = executable_root / relative
|
|
1483
|
+
target_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
|
|
1484
|
+
shutil.copyfile(source_path, target_path)
|
|
1485
|
+
target_path.chmod(stat.S_IMODE(source_path.stat().st_mode) & 0o755)
|
|
1486
|
+
hashes[f"executable/{relative}"] = sha256_file(target_path)
|
|
1487
|
+
return aggregate_hash(hashes), hashes
|
|
1488
|
+
|
|
1489
|
+
|
|
1490
|
+
def verify_bundle(bundle: Path, expected_tool: str | None = None) -> dict[str, Any]:
|
|
1491
|
+
require_owned_directory(bundle)
|
|
1492
|
+
release = read_json(bundle / "release_manifest.json")
|
|
1493
|
+
manifest = read_json(bundle / "tool_skill_manifest.json")
|
|
1494
|
+
contract = read_json(bundle / "tool_cli_contract.json")
|
|
1495
|
+
if release.get("schema_version") != SCHEMA_VERSION:
|
|
1496
|
+
raise SyncError("unsupported ToolReleaseBundle schema_version")
|
|
1497
|
+
if set(release) != {
|
|
1498
|
+
"schema_version",
|
|
1499
|
+
"tool_name",
|
|
1500
|
+
"tool_version",
|
|
1501
|
+
"tool_commit",
|
|
1502
|
+
"binary_or_entry_sha",
|
|
1503
|
+
"skill_sha",
|
|
1504
|
+
"cli_contract_sha",
|
|
1505
|
+
"manifest_sha",
|
|
1506
|
+
"source_state",
|
|
1507
|
+
}:
|
|
1508
|
+
raise SyncError(
|
|
1509
|
+
"ToolReleaseBundle release manifest fields do not match schema v1"
|
|
1510
|
+
)
|
|
1511
|
+
manifest_schema = manifest.get("schema_version")
|
|
1512
|
+
if manifest_schema not in {1, TOOL_SKILL_MANIFEST_SCHEMA_VERSION}:
|
|
1513
|
+
raise SyncError("unsupported bundled ToolSkillManifest schema_version")
|
|
1514
|
+
if contract.get("schema_version") != SCHEMA_VERSION:
|
|
1515
|
+
raise SyncError("unsupported bundled CLI contract schema_version")
|
|
1516
|
+
validate_manifest_static_fields(manifest, allow_legacy=True)
|
|
1517
|
+
validate_install_targets(manifest, allow_legacy=True)
|
|
1518
|
+
validate_contract_shape(contract)
|
|
1519
|
+
tool = release.get("tool_name")
|
|
1520
|
+
if expected_tool is not None and tool != expected_tool:
|
|
1521
|
+
raise SyncError("ToolReleaseBundle tool mismatch")
|
|
1522
|
+
if manifest.get("tool_name") != tool or contract.get("tool_name") != tool:
|
|
1523
|
+
raise SyncError("ToolReleaseBundle identity mismatch")
|
|
1524
|
+
if not (
|
|
1525
|
+
release.get("tool_version")
|
|
1526
|
+
== manifest.get("tool_version")
|
|
1527
|
+
== contract.get("tool_version")
|
|
1528
|
+
):
|
|
1529
|
+
raise SyncError("ToolReleaseBundle version mismatch")
|
|
1530
|
+
if manifest.get("tool_commit") != release.get("tool_commit"):
|
|
1531
|
+
raise SyncError("ToolReleaseBundle commit mismatch")
|
|
1532
|
+
tool_commit = release.get("tool_commit")
|
|
1533
|
+
source_state = release.get("source_state")
|
|
1534
|
+
if source_state == "committed_release":
|
|
1535
|
+
if not isinstance(tool_commit, str) or not FULL_GIT_OID.fullmatch(tool_commit):
|
|
1536
|
+
raise SyncError("committed bundle does not bind a full Git OID")
|
|
1537
|
+
elif source_state == "dirty_test_only":
|
|
1538
|
+
if (
|
|
1539
|
+
not isinstance(tool_commit, str)
|
|
1540
|
+
or not tool_commit.startswith("worktree:")
|
|
1541
|
+
or not FULL_GIT_OID.fullmatch(tool_commit.removeprefix("worktree:"))
|
|
1542
|
+
):
|
|
1543
|
+
raise SyncError("dirty test bundle has invalid worktree identity")
|
|
1544
|
+
else:
|
|
1545
|
+
raise SyncError("ToolReleaseBundle source_state is invalid")
|
|
1546
|
+
hashes = {
|
|
1547
|
+
"skill_sha": tree_sha256(bundle, SKILL_PAYLOAD),
|
|
1548
|
+
"cli_contract_sha": sha256_file(bundle / "tool_cli_contract.json"),
|
|
1549
|
+
"manifest_sha": sha256_file(bundle / "tool_skill_manifest.json"),
|
|
1550
|
+
}
|
|
1551
|
+
for key, value in hashes.items():
|
|
1552
|
+
if release.get(key) != value:
|
|
1553
|
+
raise SyncError(f"ToolReleaseBundle {key} mismatch")
|
|
1554
|
+
if manifest.get("canonical_skill_sha256") != hashes["skill_sha"]:
|
|
1555
|
+
raise SyncError("bundle Skill does not match ToolSkillManifest")
|
|
1556
|
+
if manifest_schema == TOOL_SKILL_MANIFEST_SCHEMA_VERSION:
|
|
1557
|
+
compatibility_path = bundle / COMPATIBILITY_BUNDLE_PATH
|
|
1558
|
+
require_regular(compatibility_path, "bundled compatibility Skill")
|
|
1559
|
+
if sha256_file(compatibility_path) != manifest["compatibility_skill"]["sha256"]:
|
|
1560
|
+
raise SyncError(
|
|
1561
|
+
"bundle compatibility Skill does not match ToolSkillManifest"
|
|
1562
|
+
)
|
|
1563
|
+
if manifest.get("public_cli_contract_sha256") != hashes["cli_contract_sha"]:
|
|
1564
|
+
raise SyncError("bundle CLI contract does not match ToolSkillManifest")
|
|
1565
|
+
executable = manifest.get("executable", {})
|
|
1566
|
+
if executable.get("kind") == "python_console_scripts":
|
|
1567
|
+
identity_path = bundle / "executable_identity.json"
|
|
1568
|
+
executable_hash = sha256_file(identity_path)
|
|
1569
|
+
elif executable.get("kind") == "source_files":
|
|
1570
|
+
file_hashes = {
|
|
1571
|
+
f"executable/{relative}": sha256_file(bundle / "executable" / relative)
|
|
1572
|
+
for relative in executable.get("paths", [])
|
|
1573
|
+
}
|
|
1574
|
+
executable_hash = aggregate_hash(file_hashes)
|
|
1575
|
+
else:
|
|
1576
|
+
raise SyncError("bundle executable kind is unsupported")
|
|
1577
|
+
if release.get("binary_or_entry_sha") != executable_hash:
|
|
1578
|
+
raise SyncError("ToolReleaseBundle executable identity mismatch")
|
|
1579
|
+
return release
|
|
1580
|
+
|
|
1581
|
+
|
|
1582
|
+
def smoke_bundle(bundle: Path) -> None:
|
|
1583
|
+
release = verify_bundle(bundle)
|
|
1584
|
+
manifest = read_json(bundle / "tool_skill_manifest.json")
|
|
1585
|
+
if manifest["executable"]["kind"] == "python_console_scripts":
|
|
1586
|
+
identity = read_json(bundle / "executable_identity.json")
|
|
1587
|
+
if identity.get("tool_version") != release.get("tool_version"):
|
|
1588
|
+
raise SyncError("entrypoint identity smoke failed")
|
|
1589
|
+
return
|
|
1590
|
+
entry = bundle / "executable" / manifest["executable"]["entrypoints"][0]
|
|
1591
|
+
result = run((str(entry), "--version"))
|
|
1592
|
+
if result.returncode != 0 or extract_version(
|
|
1593
|
+
result.stdout + result.stderr
|
|
1594
|
+
) != release.get("tool_version"):
|
|
1595
|
+
raise SyncError("bundled executable --version smoke failed")
|
|
1596
|
+
sync_entry = bundle / "executable" / "tool-skill-sync"
|
|
1597
|
+
if sync_entry.exists():
|
|
1598
|
+
result = run((str(sync_entry), "--version"))
|
|
1599
|
+
if result.returncode != 0 or extract_version(
|
|
1600
|
+
result.stdout + result.stderr
|
|
1601
|
+
) != bundled_sync_version(bundle):
|
|
1602
|
+
raise SyncError("bundled tool-skill-sync --version smoke failed")
|
|
1603
|
+
|
|
1604
|
+
|
|
1605
|
+
def atomic_symlink(directory: Path, name: str, target: Path) -> None:
|
|
1606
|
+
temporary = directory / f".{name}.{os.getpid()}"
|
|
1607
|
+
if temporary.exists() or temporary.is_symlink():
|
|
1608
|
+
temporary.unlink()
|
|
1609
|
+
relative = os.path.relpath(target, directory)
|
|
1610
|
+
os.symlink(relative, temporary)
|
|
1611
|
+
os.replace(temporary, directory / name)
|
|
1612
|
+
descriptor = os.open(directory, os.O_RDONLY)
|
|
1613
|
+
try:
|
|
1614
|
+
os.fsync(descriptor)
|
|
1615
|
+
finally:
|
|
1616
|
+
os.close(descriptor)
|
|
1617
|
+
|
|
1618
|
+
|
|
1619
|
+
def resolve_pointer(pointer: Path, bundles_root: Path) -> Path | None:
|
|
1620
|
+
if not pointer.exists() and not pointer.is_symlink():
|
|
1621
|
+
return None
|
|
1622
|
+
if not pointer.is_symlink():
|
|
1623
|
+
raise SyncError(f"bundle pointer is not a symlink: {pointer}")
|
|
1624
|
+
resolved = pointer.resolve(strict=True)
|
|
1625
|
+
try:
|
|
1626
|
+
resolved.relative_to(bundles_root.resolve())
|
|
1627
|
+
except ValueError as exc:
|
|
1628
|
+
raise SyncError(f"bundle pointer escapes managed root: {pointer}") from exc
|
|
1629
|
+
return resolved
|
|
1630
|
+
|
|
1631
|
+
|
|
1632
|
+
def fsync_directory(path: Path) -> None:
|
|
1633
|
+
descriptor = os.open(path, os.O_RDONLY)
|
|
1634
|
+
try:
|
|
1635
|
+
os.fsync(descriptor)
|
|
1636
|
+
finally:
|
|
1637
|
+
os.close(descriptor)
|
|
1638
|
+
|
|
1639
|
+
|
|
1640
|
+
def require_owned_regular(path: Path, label: str) -> None:
|
|
1641
|
+
require_regular(path, label)
|
|
1642
|
+
if path.stat().st_uid != os.getuid():
|
|
1643
|
+
raise SyncError(f"{label} is not owned by current user: {path}")
|
|
1644
|
+
|
|
1645
|
+
|
|
1646
|
+
def ensure_owned_subdirectory(root: Path, relative: Path) -> Path:
|
|
1647
|
+
require_owned_directory(root, create=True)
|
|
1648
|
+
current = root
|
|
1649
|
+
for part in relative.parts:
|
|
1650
|
+
if part in {"", ".", ".."}:
|
|
1651
|
+
raise SyncError(f"unsafe production directory component: {relative}")
|
|
1652
|
+
current /= part
|
|
1653
|
+
require_owned_directory(current, create=True)
|
|
1654
|
+
return current
|
|
1655
|
+
|
|
1656
|
+
|
|
1657
|
+
def production_target_sources(
|
|
1658
|
+
bundle: Path,
|
|
1659
|
+
*,
|
|
1660
|
+
agents_root: Path,
|
|
1661
|
+
bin_dir: Path | None,
|
|
1662
|
+
hooks_dir: Path,
|
|
1663
|
+
assert_installed_version: bool = True,
|
|
1664
|
+
) -> tuple[dict[Path, Path], Path | None]:
|
|
1665
|
+
manifest = read_json(bundle / "tool_skill_manifest.json")
|
|
1666
|
+
entrypoints = validate_install_targets(manifest, allow_legacy=True)
|
|
1667
|
+
require_owned_directory(agents_root)
|
|
1668
|
+
skill_parent = ensure_owned_subdirectory(agents_root, Path("skills"))
|
|
1669
|
+
manifest_schema = manifest.get("schema_version")
|
|
1670
|
+
installed_skill_name = (
|
|
1671
|
+
COMPATIBILITY_SKILL_NAME if manifest_schema == 1 else SKILL_NAME
|
|
1672
|
+
)
|
|
1673
|
+
skill_root = ensure_owned_subdirectory(skill_parent, Path(installed_skill_name))
|
|
1674
|
+
targets: dict[Path, Path] = {}
|
|
1675
|
+
for skill_relative in SKILL_PAYLOAD:
|
|
1676
|
+
target = skill_root / skill_relative
|
|
1677
|
+
ensure_owned_subdirectory(skill_root, Path(skill_relative).parent)
|
|
1678
|
+
targets[target] = bundle / skill_relative
|
|
1679
|
+
if manifest_schema == TOOL_SKILL_MANIFEST_SCHEMA_VERSION:
|
|
1680
|
+
compatibility_root = ensure_owned_subdirectory(
|
|
1681
|
+
skill_parent, Path(COMPATIBILITY_SKILL_NAME)
|
|
1682
|
+
)
|
|
1683
|
+
compatibility_target = compatibility_root / "SKILL.md"
|
|
1684
|
+
targets[compatibility_target] = bundle / COMPATIBILITY_BUNDLE_PATH
|
|
1685
|
+
|
|
1686
|
+
executable = manifest["executable"]
|
|
1687
|
+
if executable["kind"] == "python_console_scripts":
|
|
1688
|
+
if assert_installed_version:
|
|
1689
|
+
binary = installed_binary_state(entrypoints, bin_dir)
|
|
1690
|
+
if binary["version"] != manifest["tool_version"]:
|
|
1691
|
+
raise SyncError(
|
|
1692
|
+
f"installed entrypoints do not match {manifest['tool_name']} "
|
|
1693
|
+
f"{manifest['tool_version']}"
|
|
1694
|
+
)
|
|
1695
|
+
return targets, bin_dir
|
|
1696
|
+
|
|
1697
|
+
if bin_dir is None:
|
|
1698
|
+
primary = resolve_entry(entrypoints[0], None)
|
|
1699
|
+
if primary is None:
|
|
1700
|
+
raise SyncError(f"stable entry is unavailable: {entrypoints[0]}")
|
|
1701
|
+
live_bin_dir = primary.parent
|
|
1702
|
+
else:
|
|
1703
|
+
live_bin_dir = bin_dir.resolve()
|
|
1704
|
+
require_owned_directory(live_bin_dir)
|
|
1705
|
+
roots = {"bin": live_bin_dir, "hooks": hooks_dir}
|
|
1706
|
+
for source_relative, target_relative in executable["production_targets"].items():
|
|
1707
|
+
target_path = Path(target_relative)
|
|
1708
|
+
root = roots[target_path.parts[0]]
|
|
1709
|
+
require_owned_directory(root)
|
|
1710
|
+
within_root = Path(*target_path.parts[1:])
|
|
1711
|
+
if not within_root.parts:
|
|
1712
|
+
raise SyncError("production target must name a file")
|
|
1713
|
+
ensure_owned_subdirectory(root, within_root.parent)
|
|
1714
|
+
target = root / within_root
|
|
1715
|
+
if target in targets:
|
|
1716
|
+
raise SyncError(f"duplicate production target: {target}")
|
|
1717
|
+
targets[target] = bundle / "executable" / source_relative
|
|
1718
|
+
return targets, live_bin_dir
|
|
1719
|
+
|
|
1720
|
+
|
|
1721
|
+
def verify_production_bundle(
|
|
1722
|
+
bundle: Path,
|
|
1723
|
+
*,
|
|
1724
|
+
agents_root: Path,
|
|
1725
|
+
bin_dir: Path | None,
|
|
1726
|
+
hooks_dir: Path,
|
|
1727
|
+
) -> dict[str, Any]:
|
|
1728
|
+
release = verify_bundle(bundle)
|
|
1729
|
+
manifest = read_json(bundle / "tool_skill_manifest.json")
|
|
1730
|
+
targets, live_bin_dir = production_target_sources(
|
|
1731
|
+
bundle,
|
|
1732
|
+
agents_root=agents_root,
|
|
1733
|
+
bin_dir=bin_dir,
|
|
1734
|
+
hooks_dir=hooks_dir,
|
|
1735
|
+
)
|
|
1736
|
+
for target, source in targets.items():
|
|
1737
|
+
require_owned_regular(target, "active production target")
|
|
1738
|
+
if sha256_file(target) != sha256_file(source):
|
|
1739
|
+
raise SyncError(f"active production target SHA mismatch: {target}")
|
|
1740
|
+
manifest_schema = manifest.get("schema_version")
|
|
1741
|
+
installed_skill_name = (
|
|
1742
|
+
COMPATIBILITY_SKILL_NAME if manifest_schema == 1 else SKILL_NAME
|
|
1743
|
+
)
|
|
1744
|
+
if (
|
|
1745
|
+
tree_sha256(
|
|
1746
|
+
agents_root / "skills" / installed_skill_name,
|
|
1747
|
+
SKILL_PAYLOAD,
|
|
1748
|
+
)
|
|
1749
|
+
!= release["skill_sha"]
|
|
1750
|
+
):
|
|
1751
|
+
raise SyncError("active Skill SHA does not match ToolReleaseBundle")
|
|
1752
|
+
if manifest_schema == TOOL_SKILL_MANIFEST_SCHEMA_VERSION:
|
|
1753
|
+
compatibility_path = (
|
|
1754
|
+
agents_root / "skills" / COMPATIBILITY_SKILL_NAME / "SKILL.md"
|
|
1755
|
+
)
|
|
1756
|
+
require_owned_regular(compatibility_path, "active compatibility Skill")
|
|
1757
|
+
if sha256_file(compatibility_path) != manifest["compatibility_skill"]["sha256"]:
|
|
1758
|
+
raise SyncError("active compatibility Skill SHA does not match bundle")
|
|
1759
|
+
|
|
1760
|
+
entrypoints = validate_install_targets(manifest, allow_legacy=True)
|
|
1761
|
+
binary = installed_binary_state(entrypoints, live_bin_dir)
|
|
1762
|
+
if binary["version"] != release["tool_version"]:
|
|
1763
|
+
raise SyncError("active stable entry version does not match ToolReleaseBundle")
|
|
1764
|
+
if manifest["executable"]["kind"] == "source_files":
|
|
1765
|
+
sync_entry = next(
|
|
1766
|
+
(
|
|
1767
|
+
target
|
|
1768
|
+
for target, source in targets.items()
|
|
1769
|
+
if source.name == "tool-skill-sync"
|
|
1770
|
+
),
|
|
1771
|
+
None,
|
|
1772
|
+
)
|
|
1773
|
+
if sync_entry is not None:
|
|
1774
|
+
result = run((str(sync_entry), "--version"))
|
|
1775
|
+
if result.returncode != 0 or extract_version(
|
|
1776
|
+
result.stdout + result.stderr
|
|
1777
|
+
) != bundled_sync_version(bundle):
|
|
1778
|
+
raise SyncError("active tool-skill-sync smoke failed")
|
|
1779
|
+
return {
|
|
1780
|
+
"binary_version": binary["version"],
|
|
1781
|
+
"binary_sha256": binary["sha256"],
|
|
1782
|
+
"skill_sha256": release["skill_sha"],
|
|
1783
|
+
"cli_contract_sha256": release["cli_contract_sha"],
|
|
1784
|
+
"target_sha256": {
|
|
1785
|
+
str(target): sha256_file(target) for target in sorted(targets)
|
|
1786
|
+
},
|
|
1787
|
+
}
|
|
1788
|
+
|
|
1789
|
+
|
|
1790
|
+
def production_pair_matches(
|
|
1791
|
+
bundle: Path,
|
|
1792
|
+
*,
|
|
1793
|
+
agents_root: Path,
|
|
1794
|
+
bin_dir: Path | None,
|
|
1795
|
+
hooks_dir: Path,
|
|
1796
|
+
) -> bool:
|
|
1797
|
+
targets, _ = production_target_sources(
|
|
1798
|
+
bundle,
|
|
1799
|
+
agents_root=agents_root,
|
|
1800
|
+
bin_dir=bin_dir,
|
|
1801
|
+
hooks_dir=hooks_dir,
|
|
1802
|
+
)
|
|
1803
|
+
for target, source in targets.items():
|
|
1804
|
+
if not target.exists() and not target.is_symlink():
|
|
1805
|
+
return False
|
|
1806
|
+
require_owned_regular(target, "active production target")
|
|
1807
|
+
if sha256_file(target) != sha256_file(source):
|
|
1808
|
+
return False
|
|
1809
|
+
verify_production_bundle(
|
|
1810
|
+
bundle,
|
|
1811
|
+
agents_root=agents_root,
|
|
1812
|
+
bin_dir=bin_dir,
|
|
1813
|
+
hooks_dir=hooks_dir,
|
|
1814
|
+
)
|
|
1815
|
+
return True
|
|
1816
|
+
|
|
1817
|
+
|
|
1818
|
+
def verify_production_backup(backup: Path) -> dict[str, Any]:
|
|
1819
|
+
require_owned_directory(backup)
|
|
1820
|
+
receipt = read_json(backup / "receipt.json")
|
|
1821
|
+
if set(receipt) != {"schema_version", "operation", "tool", "entries"} or (
|
|
1822
|
+
receipt.get("schema_version") != SCHEMA_VERSION
|
|
1823
|
+
or receipt.get("operation") != "production_pair_backup"
|
|
1824
|
+
or not isinstance(receipt.get("tool"), str)
|
|
1825
|
+
or not isinstance(receipt.get("entries"), list)
|
|
1826
|
+
):
|
|
1827
|
+
raise SyncError("production backup receipt is invalid")
|
|
1828
|
+
seen: set[str] = set()
|
|
1829
|
+
for entry in receipt["entries"]:
|
|
1830
|
+
if not isinstance(entry, dict) or set(entry) != {
|
|
1831
|
+
"target",
|
|
1832
|
+
"backup_file",
|
|
1833
|
+
"sha256",
|
|
1834
|
+
"mode",
|
|
1835
|
+
}:
|
|
1836
|
+
raise SyncError("production backup entry is invalid")
|
|
1837
|
+
target = entry["target"]
|
|
1838
|
+
if (
|
|
1839
|
+
not isinstance(target, str)
|
|
1840
|
+
or not Path(target).is_absolute()
|
|
1841
|
+
or target in seen
|
|
1842
|
+
):
|
|
1843
|
+
raise SyncError("production backup target is invalid or duplicated")
|
|
1844
|
+
seen.add(target)
|
|
1845
|
+
backup_file = entry["backup_file"]
|
|
1846
|
+
digest = entry["sha256"]
|
|
1847
|
+
mode = entry["mode"]
|
|
1848
|
+
if backup_file is None:
|
|
1849
|
+
if digest is not None or mode is not None:
|
|
1850
|
+
raise SyncError("absent production backup entry has file metadata")
|
|
1851
|
+
continue
|
|
1852
|
+
if (
|
|
1853
|
+
not isinstance(backup_file, str)
|
|
1854
|
+
or Path(backup_file).is_absolute()
|
|
1855
|
+
or ".." in Path(backup_file).parts
|
|
1856
|
+
or not isinstance(digest, str)
|
|
1857
|
+
or not HEX_SHA256.fullmatch(digest)
|
|
1858
|
+
or not isinstance(mode, int)
|
|
1859
|
+
):
|
|
1860
|
+
raise SyncError("production backup file metadata is invalid")
|
|
1861
|
+
stored = backup / backup_file
|
|
1862
|
+
require_owned_regular(stored, "production backup file")
|
|
1863
|
+
if sha256_file(stored) != digest:
|
|
1864
|
+
raise SyncError("production backup file SHA mismatch")
|
|
1865
|
+
return receipt
|
|
1866
|
+
|
|
1867
|
+
|
|
1868
|
+
def capture_production_pair(
|
|
1869
|
+
tool: str,
|
|
1870
|
+
targets: Sequence[Path],
|
|
1871
|
+
production_root: Path,
|
|
1872
|
+
) -> Path:
|
|
1873
|
+
backups_root = ensure_owned_subdirectory(production_root, Path("backups"))
|
|
1874
|
+
staging = Path(tempfile.mkdtemp(prefix=".staging-", dir=backups_root))
|
|
1875
|
+
staging.chmod(0o700)
|
|
1876
|
+
try:
|
|
1877
|
+
entries: list[dict[str, Any]] = []
|
|
1878
|
+
files_root = staging / "files"
|
|
1879
|
+
files_root.mkdir(mode=0o700)
|
|
1880
|
+
for index, target in enumerate(sorted(targets)):
|
|
1881
|
+
if not target.exists() and not target.is_symlink():
|
|
1882
|
+
entries.append(
|
|
1883
|
+
{
|
|
1884
|
+
"target": str(target),
|
|
1885
|
+
"backup_file": None,
|
|
1886
|
+
"sha256": None,
|
|
1887
|
+
"mode": None,
|
|
1888
|
+
}
|
|
1889
|
+
)
|
|
1890
|
+
continue
|
|
1891
|
+
require_owned_regular(target, "active production target")
|
|
1892
|
+
relative = f"files/{index:03d}"
|
|
1893
|
+
stored = staging / relative
|
|
1894
|
+
shutil.copyfile(target, stored)
|
|
1895
|
+
mode = stat.S_IMODE(target.stat().st_mode)
|
|
1896
|
+
stored.chmod(mode)
|
|
1897
|
+
entries.append(
|
|
1898
|
+
{
|
|
1899
|
+
"target": str(target),
|
|
1900
|
+
"backup_file": relative,
|
|
1901
|
+
"sha256": sha256_file(stored),
|
|
1902
|
+
"mode": mode,
|
|
1903
|
+
}
|
|
1904
|
+
)
|
|
1905
|
+
receipt = {
|
|
1906
|
+
"schema_version": SCHEMA_VERSION,
|
|
1907
|
+
"operation": "production_pair_backup",
|
|
1908
|
+
"tool": tool,
|
|
1909
|
+
"entries": entries,
|
|
1910
|
+
}
|
|
1911
|
+
write_json(staging / "receipt.json", receipt)
|
|
1912
|
+
identity = sha256_file(staging / "receipt.json")
|
|
1913
|
+
destination = backups_root / identity
|
|
1914
|
+
if destination.exists():
|
|
1915
|
+
verify_production_backup(destination)
|
|
1916
|
+
shutil.rmtree(staging)
|
|
1917
|
+
return destination
|
|
1918
|
+
os.replace(staging, destination)
|
|
1919
|
+
fsync_directory(backups_root)
|
|
1920
|
+
verify_production_backup(destination)
|
|
1921
|
+
return destination
|
|
1922
|
+
except BaseException:
|
|
1923
|
+
if staging.exists():
|
|
1924
|
+
shutil.rmtree(staging)
|
|
1925
|
+
raise
|
|
1926
|
+
|
|
1927
|
+
|
|
1928
|
+
def restore_production_pair(
|
|
1929
|
+
backup: Path, expected_targets: Sequence[Path], *, execution_locked: bool = False,
|
|
1930
|
+
) -> None:
|
|
1931
|
+
if not execution_locked:
|
|
1932
|
+
with finalizer_execution_lock(expected_targets):
|
|
1933
|
+
return restore_production_pair(backup, expected_targets, execution_locked=True)
|
|
1934
|
+
receipt = verify_production_backup(backup)
|
|
1935
|
+
entries = {Path(entry["target"]): entry for entry in receipt["entries"]}
|
|
1936
|
+
if set(entries) != set(expected_targets):
|
|
1937
|
+
raise SyncError("production backup target set does not match active pair")
|
|
1938
|
+
staged: dict[Path, Path] = {}
|
|
1939
|
+
try:
|
|
1940
|
+
for target, entry in entries.items():
|
|
1941
|
+
if entry["backup_file"] is None:
|
|
1942
|
+
continue
|
|
1943
|
+
ensure_owned_subdirectory(target.parent, Path("."))
|
|
1944
|
+
descriptor, temporary_name = tempfile.mkstemp(
|
|
1945
|
+
dir=target.parent, prefix=f".{target.name}.restore-"
|
|
1946
|
+
)
|
|
1947
|
+
os.close(descriptor)
|
|
1948
|
+
temporary = Path(temporary_name)
|
|
1949
|
+
shutil.copyfile(backup / entry["backup_file"], temporary)
|
|
1950
|
+
temporary.chmod(entry["mode"])
|
|
1951
|
+
staged[target] = temporary
|
|
1952
|
+
for target, entry in entries.items():
|
|
1953
|
+
if entry["backup_file"] is None:
|
|
1954
|
+
if target.exists() or target.is_symlink():
|
|
1955
|
+
require_owned_regular(target, "active production target")
|
|
1956
|
+
target.unlink()
|
|
1957
|
+
fsync_directory(target.parent)
|
|
1958
|
+
continue
|
|
1959
|
+
os.replace(staged.pop(target), target)
|
|
1960
|
+
fsync_directory(target.parent)
|
|
1961
|
+
finally:
|
|
1962
|
+
for temporary in staged.values():
|
|
1963
|
+
if temporary.exists():
|
|
1964
|
+
temporary.unlink()
|
|
1965
|
+
|
|
1966
|
+
|
|
1967
|
+
def installed_skill_tree(agents_root: Path, bundle: Path) -> str | None:
|
|
1968
|
+
manifest = read_json(bundle / "tool_skill_manifest.json")
|
|
1969
|
+
installed_skill_name = (
|
|
1970
|
+
COMPATIBILITY_SKILL_NAME
|
|
1971
|
+
if manifest.get("schema_version") == 1
|
|
1972
|
+
else SKILL_NAME
|
|
1973
|
+
)
|
|
1974
|
+
skill_root = agents_root / "skills" / installed_skill_name
|
|
1975
|
+
present = [
|
|
1976
|
+
skill_root / relative
|
|
1977
|
+
for relative in SKILL_PAYLOAD
|
|
1978
|
+
if (skill_root / relative).exists() or (skill_root / relative).is_symlink()
|
|
1979
|
+
]
|
|
1980
|
+
if not present:
|
|
1981
|
+
return None
|
|
1982
|
+
if len(present) != len(SKILL_PAYLOAD):
|
|
1983
|
+
missing = ", ".join(
|
|
1984
|
+
relative
|
|
1985
|
+
for relative in SKILL_PAYLOAD
|
|
1986
|
+
if not (skill_root / relative).exists()
|
|
1987
|
+
and not (skill_root / relative).is_symlink()
|
|
1988
|
+
)
|
|
1989
|
+
raise SyncError(
|
|
1990
|
+
"installed production Skill is incomplete; preserve and classify the "
|
|
1991
|
+
f"missing payload files before activation: {missing}"
|
|
1992
|
+
)
|
|
1993
|
+
return tree_sha256(skill_root, SKILL_PAYLOAD)
|
|
1994
|
+
|
|
1995
|
+
|
|
1996
|
+
def validate_production_skill_trusted(
|
|
1997
|
+
bundle: Path,
|
|
1998
|
+
agents_root: Path,
|
|
1999
|
+
*,
|
|
2000
|
+
previous_bundle: Path | None,
|
|
2001
|
+
) -> None:
|
|
2002
|
+
live_tree = installed_skill_tree(agents_root, bundle)
|
|
2003
|
+
if live_tree is None:
|
|
2004
|
+
return
|
|
2005
|
+
bundle_tree = verify_bundle(bundle)["skill_sha"]
|
|
2006
|
+
if live_tree == bundle_tree:
|
|
2007
|
+
return
|
|
2008
|
+
if live_tree in RELEASED_CANONICAL_SKILL_SHA256:
|
|
2009
|
+
return
|
|
2010
|
+
if previous_bundle is not None and verify_bundle(previous_bundle)["skill_sha"] == live_tree:
|
|
2011
|
+
return
|
|
2012
|
+
manifest = read_json(bundle / "tool_skill_manifest.json")
|
|
2013
|
+
installed_skill_name = (
|
|
2014
|
+
COMPATIBILITY_SKILL_NAME
|
|
2015
|
+
if manifest.get("schema_version") == 1
|
|
2016
|
+
else SKILL_NAME
|
|
2017
|
+
)
|
|
2018
|
+
skill_root = agents_root / "skills" / installed_skill_name
|
|
2019
|
+
drifted = ", ".join(
|
|
2020
|
+
f"{relative} live={sha256_file(skill_root / relative)}"
|
|
2021
|
+
for relative in SKILL_PAYLOAD
|
|
2022
|
+
if sha256_file(skill_root / relative) != sha256_file(bundle / relative)
|
|
2023
|
+
)
|
|
2024
|
+
raise SyncError(
|
|
2025
|
+
f"unknown content drift in installed production Skill (live_tree={live_tree} "
|
|
2026
|
+
f"bundle_tree={bundle_tree} accepted_released_trees="
|
|
2027
|
+
f"{', '.join(sorted(RELEASED_CANONICAL_SKILL_SHA256))}); preserve and "
|
|
2028
|
+
"classify these files first, activation refuses to overwrite them: "
|
|
2029
|
+
+ drifted
|
|
2030
|
+
)
|
|
2031
|
+
|
|
2032
|
+
|
|
2033
|
+
def replace_production_pair(targets: dict[Path, Path]) -> None:
|
|
2034
|
+
staged: dict[Path, Path] = {}
|
|
2035
|
+
try:
|
|
2036
|
+
for target, source in targets.items():
|
|
2037
|
+
require_owned_regular(source, "bundled production source")
|
|
2038
|
+
descriptor, temporary_name = tempfile.mkstemp(
|
|
2039
|
+
dir=target.parent, prefix=f".{target.name}.install-"
|
|
2040
|
+
)
|
|
2041
|
+
os.close(descriptor)
|
|
2042
|
+
temporary = Path(temporary_name)
|
|
2043
|
+
shutil.copyfile(source, temporary)
|
|
2044
|
+
temporary.chmod(stat.S_IMODE(source.stat().st_mode))
|
|
2045
|
+
staged[target] = temporary
|
|
2046
|
+
for target in sorted(staged):
|
|
2047
|
+
if target.exists() or target.is_symlink():
|
|
2048
|
+
require_owned_regular(target, "active production target")
|
|
2049
|
+
os.replace(staged.pop(target), target)
|
|
2050
|
+
fsync_directory(target.parent)
|
|
2051
|
+
finally:
|
|
2052
|
+
for temporary in staged.values():
|
|
2053
|
+
if temporary.exists():
|
|
2054
|
+
temporary.unlink()
|
|
2055
|
+
|
|
2056
|
+
|
|
2057
|
+
@contextmanager
|
|
2058
|
+
def finalizer_execution_lock(targets: Sequence[Path], *, timeout: float = DEFAULT_LOCK_TIMEOUT):
|
|
2059
|
+
"""Keep active CLI readers out of a production activation or rollback."""
|
|
2060
|
+
entries = [target for target in targets if target.name == "git-finalize"]
|
|
2061
|
+
if not entries:
|
|
2062
|
+
yield
|
|
2063
|
+
return
|
|
2064
|
+
if len(entries) != 1:
|
|
2065
|
+
raise SyncError("ambiguous Finalizer execution lock target")
|
|
2066
|
+
lock_path = entries[0].with_name(".git-finalizer-execution.lock")
|
|
2067
|
+
require_owned_directory(lock_path.parent)
|
|
2068
|
+
descriptor = os.open(lock_path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW | os.O_CLOEXEC, 0o600)
|
|
2069
|
+
try:
|
|
2070
|
+
info = os.fstat(descriptor)
|
|
2071
|
+
if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
|
|
2072
|
+
raise SyncError("unsafe Finalizer execution lock")
|
|
2073
|
+
_flock_exclusive_bounded(descriptor, timeout=timeout, label="Finalizer execution lock")
|
|
2074
|
+
yield
|
|
2075
|
+
finally:
|
|
2076
|
+
os.close(descriptor)
|
|
2077
|
+
|
|
2078
|
+
|
|
2079
|
+
def activate_production_bundle(
|
|
2080
|
+
bundle: Path,
|
|
2081
|
+
tool: str,
|
|
2082
|
+
production_root: Path,
|
|
2083
|
+
*,
|
|
2084
|
+
agents_root: Path,
|
|
2085
|
+
bin_dir: Path | None,
|
|
2086
|
+
hooks_dir: Path,
|
|
2087
|
+
previous_bundle: Path | None = None,
|
|
2088
|
+
) -> tuple[Path | None, dict[str, Any]]:
|
|
2089
|
+
targets, live_bin_dir = production_target_sources(
|
|
2090
|
+
bundle,
|
|
2091
|
+
agents_root=agents_root,
|
|
2092
|
+
bin_dir=bin_dir,
|
|
2093
|
+
hooks_dir=hooks_dir,
|
|
2094
|
+
)
|
|
2095
|
+
validate_production_skill_trusted(
|
|
2096
|
+
bundle,
|
|
2097
|
+
agents_root,
|
|
2098
|
+
previous_bundle=previous_bundle,
|
|
2099
|
+
)
|
|
2100
|
+
previous_targets = {}
|
|
2101
|
+
if previous_bundle is not None:
|
|
2102
|
+
# Transition bookkeeping only: the retired target set is a static
|
|
2103
|
+
# property of the previous manifest. Installed-version consistency is
|
|
2104
|
+
# asserted against the incoming bundle and by the post-activation
|
|
2105
|
+
# verification, never against the superseded release.
|
|
2106
|
+
prev_manifest = read_json(previous_bundle / "tool_skill_manifest.json")
|
|
2107
|
+
cur_manifest = read_json(bundle / "tool_skill_manifest.json")
|
|
2108
|
+
prev_kind = prev_manifest["executable"]["kind"]
|
|
2109
|
+
cur_kind = cur_manifest["executable"]["kind"]
|
|
2110
|
+
prev_bin_dir = live_bin_dir
|
|
2111
|
+
new_entrypoints = validate_install_targets(cur_manifest, allow_legacy=True)
|
|
2112
|
+
if prev_bin_dir is None and prev_kind == "source_files":
|
|
2113
|
+
for name in new_entrypoints:
|
|
2114
|
+
found = shutil.which(name)
|
|
2115
|
+
if found:
|
|
2116
|
+
prev_bin_dir = Path(found).parent
|
|
2117
|
+
break
|
|
2118
|
+
previous_targets, resolved_prev_bin = production_target_sources(
|
|
2119
|
+
previous_bundle,
|
|
2120
|
+
agents_root=agents_root,
|
|
2121
|
+
bin_dir=prev_bin_dir,
|
|
2122
|
+
hooks_dir=hooks_dir,
|
|
2123
|
+
assert_installed_version=False,
|
|
2124
|
+
)
|
|
2125
|
+
if prev_kind == "source_files" and cur_kind == "python_console_scripts":
|
|
2126
|
+
# Keep active console scripts managed by uv tool install; only retire
|
|
2127
|
+
# genuinely obsolete source_files sidecars and helpers.
|
|
2128
|
+
new_entry_set = set(new_entrypoints)
|
|
2129
|
+
active_console_paths: set[Path] = set()
|
|
2130
|
+
for dir_cand in (resolved_prev_bin, bin_dir.resolve() if bin_dir else None):
|
|
2131
|
+
if dir_cand is not None:
|
|
2132
|
+
for name in new_entry_set:
|
|
2133
|
+
active_console_paths.add(dir_cand / name)
|
|
2134
|
+
try:
|
|
2135
|
+
uv_info = python_tool_installation(new_entrypoints, bin_dir)
|
|
2136
|
+
active_console_paths.update(
|
|
2137
|
+
Path(entry_path) for entry_path in uv_info["entry_targets"].values()
|
|
2138
|
+
)
|
|
2139
|
+
except SyncError:
|
|
2140
|
+
pass
|
|
2141
|
+
previous_targets = {
|
|
2142
|
+
target: source
|
|
2143
|
+
for target, source in previous_targets.items()
|
|
2144
|
+
if target not in active_console_paths
|
|
2145
|
+
and not (target.name in new_entry_set and target.is_symlink())
|
|
2146
|
+
}
|
|
2147
|
+
retired = set(previous_targets) - set(targets)
|
|
2148
|
+
for target in retired:
|
|
2149
|
+
if not target.exists() and not target.is_symlink():
|
|
2150
|
+
continue
|
|
2151
|
+
require_owned_regular(target, "retiring production target")
|
|
2152
|
+
source = previous_targets[target]
|
|
2153
|
+
if (sha256_file(target) != sha256_file(source)
|
|
2154
|
+
or stat.S_IMODE(target.stat().st_mode) != stat.S_IMODE(source.stat().st_mode)):
|
|
2155
|
+
raise SyncError(f"retiring production target drifted: {target}")
|
|
2156
|
+
all_targets = tuple(set(targets) | set(previous_targets))
|
|
2157
|
+
if not retired and production_pair_matches(
|
|
2158
|
+
bundle,
|
|
2159
|
+
agents_root=agents_root,
|
|
2160
|
+
bin_dir=live_bin_dir,
|
|
2161
|
+
hooks_dir=hooks_dir,
|
|
2162
|
+
):
|
|
2163
|
+
return None, verify_production_bundle(
|
|
2164
|
+
bundle,
|
|
2165
|
+
agents_root=agents_root,
|
|
2166
|
+
bin_dir=live_bin_dir,
|
|
2167
|
+
hooks_dir=hooks_dir,
|
|
2168
|
+
)
|
|
2169
|
+
with finalizer_execution_lock(all_targets):
|
|
2170
|
+
backup = capture_production_pair(tool, all_targets, production_root)
|
|
2171
|
+
try:
|
|
2172
|
+
replace_production_pair(targets)
|
|
2173
|
+
verified = verify_production_bundle(
|
|
2174
|
+
bundle,
|
|
2175
|
+
agents_root=agents_root,
|
|
2176
|
+
bin_dir=live_bin_dir,
|
|
2177
|
+
hooks_dir=hooks_dir,
|
|
2178
|
+
)
|
|
2179
|
+
for target in retired:
|
|
2180
|
+
if target.exists():
|
|
2181
|
+
target.unlink()
|
|
2182
|
+
fsync_directory(target.parent)
|
|
2183
|
+
verified["retired_targets"] = sorted(map(str, retired))
|
|
2184
|
+
except BaseException:
|
|
2185
|
+
restore_production_pair(backup, all_targets, execution_locked=True)
|
|
2186
|
+
raise
|
|
2187
|
+
return backup, verified
|
|
2188
|
+
|
|
2189
|
+
|
|
2190
|
+
def resolve_production_backup(pointer: Path, backups_root: Path) -> Path | None:
|
|
2191
|
+
return resolve_pointer(pointer, backups_root)
|
|
2192
|
+
|
|
2193
|
+
|
|
2194
|
+
def restore_pointer(directory: Path, name: str, target: Path | None) -> None:
|
|
2195
|
+
pointer = directory / name
|
|
2196
|
+
if target is None:
|
|
2197
|
+
if pointer.exists() or pointer.is_symlink():
|
|
2198
|
+
if not pointer.is_symlink():
|
|
2199
|
+
raise SyncError(f"managed pointer is not a symlink: {pointer}")
|
|
2200
|
+
pointer.unlink()
|
|
2201
|
+
fsync_directory(directory)
|
|
2202
|
+
return
|
|
2203
|
+
atomic_symlink(directory, name, target)
|
|
2204
|
+
|
|
2205
|
+
|
|
2206
|
+
def build_bundle(
|
|
2207
|
+
sources: Sources,
|
|
2208
|
+
tool: str,
|
|
2209
|
+
bundles_root: Path,
|
|
2210
|
+
*,
|
|
2211
|
+
allow_dirty_source: bool,
|
|
2212
|
+
) -> Path:
|
|
2213
|
+
checked = check_tool(sources, tool)
|
|
2214
|
+
if checked["status"] != "PASS":
|
|
2215
|
+
raise SyncError("canonical check failed: " + "; ".join(checked["errors"]))
|
|
2216
|
+
repo = sources.repo(tool)
|
|
2217
|
+
head = sources.head(tool)
|
|
2218
|
+
dirty = sources.dirty(tool) or git_dirty(sources.owner_repo)
|
|
2219
|
+
if dirty and not allow_dirty_source:
|
|
2220
|
+
raise SyncError(
|
|
2221
|
+
"source repositories are dirty; release bundle requires committed sources"
|
|
2222
|
+
)
|
|
2223
|
+
tool_commit = f"worktree:{head}" if dirty else head
|
|
2224
|
+
manifest = read_json(sources.manifest_path(tool))
|
|
2225
|
+
manifest["tool_commit"] = tool_commit
|
|
2226
|
+
tool_root = bundles_root / tool
|
|
2227
|
+
require_owned_directory(tool_root, create=True)
|
|
2228
|
+
staging = Path(tempfile.mkdtemp(prefix=".staging-", dir=tool_root))
|
|
2229
|
+
staging.chmod(0o700)
|
|
2230
|
+
try:
|
|
2231
|
+
copy_skill_payload(sources.skill_root, staging)
|
|
2232
|
+
copy_compatibility_skill(sources.compatibility_skill_root, staging)
|
|
2233
|
+
(staging / "tool_cli_contract.json").write_bytes(
|
|
2234
|
+
sources.source_bytes(tool, "tool_cli_contract.json")
|
|
2235
|
+
)
|
|
2236
|
+
(staging / "tool_cli_contract.json").chmod(0o600)
|
|
2237
|
+
write_json(staging / "tool_skill_manifest.json", manifest)
|
|
2238
|
+
executable_sha, _ = source_executable_payload(
|
|
2239
|
+
repo, manifest, staging, tool_commit
|
|
2240
|
+
)
|
|
2241
|
+
release = {
|
|
2242
|
+
"schema_version": SCHEMA_VERSION,
|
|
2243
|
+
"tool_name": tool,
|
|
2244
|
+
"tool_version": manifest["tool_version"],
|
|
2245
|
+
"tool_commit": tool_commit,
|
|
2246
|
+
"binary_or_entry_sha": executable_sha,
|
|
2247
|
+
"skill_sha": tree_sha256(staging, SKILL_PAYLOAD),
|
|
2248
|
+
"cli_contract_sha": sha256_file(staging / "tool_cli_contract.json"),
|
|
2249
|
+
"manifest_sha": sha256_file(staging / "tool_skill_manifest.json"),
|
|
2250
|
+
"source_state": "dirty_test_only" if dirty else "committed_release",
|
|
2251
|
+
}
|
|
2252
|
+
write_json(staging / "release_manifest.json", release)
|
|
2253
|
+
verify_bundle(staging, tool)
|
|
2254
|
+
smoke_bundle(staging)
|
|
2255
|
+
release_sha = sha256_file(staging / "release_manifest.json")
|
|
2256
|
+
safe_commit = tool_commit.replace(":", "-")[:21]
|
|
2257
|
+
bundle_name = f"{manifest['tool_version']}-{safe_commit}-{release_sha[:12]}"
|
|
2258
|
+
destination = tool_root / bundle_name
|
|
2259
|
+
if destination.exists():
|
|
2260
|
+
verify_bundle(destination, tool)
|
|
2261
|
+
shutil.rmtree(staging)
|
|
2262
|
+
return destination
|
|
2263
|
+
os.replace(staging, destination)
|
|
2264
|
+
return destination
|
|
2265
|
+
except BaseException:
|
|
2266
|
+
if staging.exists():
|
|
2267
|
+
shutil.rmtree(staging)
|
|
2268
|
+
raise
|
|
2269
|
+
|
|
2270
|
+
|
|
2271
|
+
def install(
|
|
2272
|
+
sources: Sources,
|
|
2273
|
+
tool: str,
|
|
2274
|
+
install_root: Path,
|
|
2275
|
+
*,
|
|
2276
|
+
allow_dirty_source: bool,
|
|
2277
|
+
activate_production: bool = False,
|
|
2278
|
+
agents_root: Path | None = None,
|
|
2279
|
+
bin_dir: Path | None = None,
|
|
2280
|
+
hooks_dir: Path | None = None,
|
|
2281
|
+
) -> dict[str, Any]:
|
|
2282
|
+
roots = [install_root]
|
|
2283
|
+
if activate_production and agents_root is not None:
|
|
2284
|
+
roots.append(agents_root / "skills")
|
|
2285
|
+
with deployment_lock(*roots):
|
|
2286
|
+
return _install_unlocked(
|
|
2287
|
+
sources, tool, install_root, allow_dirty_source=allow_dirty_source,
|
|
2288
|
+
activate_production=activate_production, agents_root=agents_root,
|
|
2289
|
+
bin_dir=bin_dir, hooks_dir=hooks_dir,
|
|
2290
|
+
)
|
|
2291
|
+
|
|
2292
|
+
|
|
2293
|
+
def _install_unlocked(
|
|
2294
|
+
sources: Sources, tool: str, install_root: Path, *, allow_dirty_source: bool,
|
|
2295
|
+
activate_production: bool = False, agents_root: Path | None = None,
|
|
2296
|
+
bin_dir: Path | None = None, hooks_dir: Path | None = None,
|
|
2297
|
+
) -> dict[str, Any]:
|
|
2298
|
+
require_owned_directory(install_root, create=True)
|
|
2299
|
+
bundles_root = install_root / "bundles"
|
|
2300
|
+
state_root = install_root / "tools" / tool
|
|
2301
|
+
require_owned_directory(bundles_root, create=True)
|
|
2302
|
+
require_owned_directory(state_root, create=True)
|
|
2303
|
+
bundle = build_bundle(
|
|
2304
|
+
sources,
|
|
2305
|
+
tool,
|
|
2306
|
+
bundles_root,
|
|
2307
|
+
allow_dirty_source=allow_dirty_source,
|
|
2308
|
+
)
|
|
2309
|
+
current = resolve_pointer(state_root / "CURRENT", bundles_root)
|
|
2310
|
+
if current == bundle and not activate_production:
|
|
2311
|
+
return {"status": "UNCHANGED", "tool": tool, "current_bundle": bundle.name}
|
|
2312
|
+
previous_before = resolve_pointer(state_root / "PREVIOUS", bundles_root)
|
|
2313
|
+
if current is not None:
|
|
2314
|
+
verify_bundle(current, tool)
|
|
2315
|
+
smoke_bundle(current)
|
|
2316
|
+
|
|
2317
|
+
production_root: Path | None = None
|
|
2318
|
+
production_previous: Path | None = None
|
|
2319
|
+
production_backup: Path | None = None
|
|
2320
|
+
production_verified: dict[str, Any] | None = None
|
|
2321
|
+
if activate_production:
|
|
2322
|
+
if agents_root is None or hooks_dir is None:
|
|
2323
|
+
raise SyncError("production activation requires agents_root and hooks_dir")
|
|
2324
|
+
production_root = state_root / "production"
|
|
2325
|
+
require_owned_directory(production_root, create=True)
|
|
2326
|
+
backups_root = ensure_owned_subdirectory(production_root, Path("backups"))
|
|
2327
|
+
production_previous = resolve_production_backup(
|
|
2328
|
+
production_root / "PREVIOUS", backups_root
|
|
2329
|
+
)
|
|
2330
|
+
production_backup, production_verified = activate_production_bundle(
|
|
2331
|
+
bundle,
|
|
2332
|
+
tool,
|
|
2333
|
+
production_root,
|
|
2334
|
+
agents_root=agents_root,
|
|
2335
|
+
bin_dir=bin_dir,
|
|
2336
|
+
hooks_dir=hooks_dir,
|
|
2337
|
+
previous_bundle=current,
|
|
2338
|
+
)
|
|
2339
|
+
|
|
2340
|
+
try:
|
|
2341
|
+
if current != bundle:
|
|
2342
|
+
if current is not None:
|
|
2343
|
+
atomic_symlink(state_root, "PREVIOUS", current)
|
|
2344
|
+
atomic_symlink(state_root, "CURRENT", bundle)
|
|
2345
|
+
active = resolve_pointer(state_root / "CURRENT", bundles_root)
|
|
2346
|
+
verify_bundle(active or bundle, tool)
|
|
2347
|
+
if production_backup is not None and production_root is not None:
|
|
2348
|
+
atomic_symlink(production_root, "PREVIOUS", production_backup)
|
|
2349
|
+
if activate_production:
|
|
2350
|
+
assert agents_root is not None
|
|
2351
|
+
assert hooks_dir is not None
|
|
2352
|
+
production_verified = verify_production_bundle(
|
|
2353
|
+
bundle,
|
|
2354
|
+
agents_root=agents_root,
|
|
2355
|
+
bin_dir=bin_dir,
|
|
2356
|
+
hooks_dir=hooks_dir,
|
|
2357
|
+
)
|
|
2358
|
+
except BaseException:
|
|
2359
|
+
if production_backup is not None:
|
|
2360
|
+
# Failure cleanup must never be blocked by pairing assertions;
|
|
2361
|
+
# these calls only rebuild the target set for byte-verified
|
|
2362
|
+
# restoration from the recorded backup.
|
|
2363
|
+
targets, _ = production_target_sources(
|
|
2364
|
+
bundle,
|
|
2365
|
+
agents_root=agents_root or Path(),
|
|
2366
|
+
bin_dir=bin_dir,
|
|
2367
|
+
hooks_dir=hooks_dir or Path(),
|
|
2368
|
+
assert_installed_version=False,
|
|
2369
|
+
)
|
|
2370
|
+
if current is not None:
|
|
2371
|
+
previous_targets, _ = production_target_sources(
|
|
2372
|
+
current, agents_root=agents_root or Path(), bin_dir=bin_dir,
|
|
2373
|
+
hooks_dir=hooks_dir or Path(),
|
|
2374
|
+
assert_installed_version=False,
|
|
2375
|
+
)
|
|
2376
|
+
targets.update(previous_targets)
|
|
2377
|
+
restore_production_pair(production_backup, tuple(targets))
|
|
2378
|
+
restore_pointer(state_root, "CURRENT", current)
|
|
2379
|
+
restore_pointer(state_root, "PREVIOUS", previous_before)
|
|
2380
|
+
if production_root is not None:
|
|
2381
|
+
restore_pointer(production_root, "PREVIOUS", production_previous)
|
|
2382
|
+
raise
|
|
2383
|
+
return {
|
|
2384
|
+
"status": "INSTALLED" if current != bundle else "ACTIVATED",
|
|
2385
|
+
"tool": tool,
|
|
2386
|
+
"current_bundle": bundle.name,
|
|
2387
|
+
"previous_bundle": current.name if current else None,
|
|
2388
|
+
"production_activation": activate_production,
|
|
2389
|
+
"production_verified": production_verified,
|
|
2390
|
+
}
|
|
2391
|
+
|
|
2392
|
+
|
|
2393
|
+
def rollback(
|
|
2394
|
+
tool: str,
|
|
2395
|
+
install_root: Path,
|
|
2396
|
+
*,
|
|
2397
|
+
activate_production: bool = False,
|
|
2398
|
+
agents_root: Path | None = None,
|
|
2399
|
+
bin_dir: Path | None = None,
|
|
2400
|
+
hooks_dir: Path | None = None,
|
|
2401
|
+
) -> dict[str, Any]:
|
|
2402
|
+
roots = [install_root]
|
|
2403
|
+
if activate_production and agents_root is not None:
|
|
2404
|
+
roots.append(agents_root / "skills")
|
|
2405
|
+
with deployment_lock(*roots):
|
|
2406
|
+
return _rollback_unlocked(
|
|
2407
|
+
tool, install_root, activate_production=activate_production,
|
|
2408
|
+
agents_root=agents_root, bin_dir=bin_dir, hooks_dir=hooks_dir,
|
|
2409
|
+
)
|
|
2410
|
+
|
|
2411
|
+
|
|
2412
|
+
def _rollback_unlocked(
|
|
2413
|
+
tool: str, install_root: Path, *, activate_production: bool = False,
|
|
2414
|
+
agents_root: Path | None = None, bin_dir: Path | None = None,
|
|
2415
|
+
hooks_dir: Path | None = None,
|
|
2416
|
+
) -> dict[str, Any]:
|
|
2417
|
+
bundles_root = install_root / "bundles"
|
|
2418
|
+
state_root = install_root / "tools" / tool
|
|
2419
|
+
require_owned_directory(bundles_root)
|
|
2420
|
+
require_owned_directory(state_root)
|
|
2421
|
+
current = resolve_pointer(state_root / "CURRENT", bundles_root)
|
|
2422
|
+
previous = resolve_pointer(state_root / "PREVIOUS", bundles_root)
|
|
2423
|
+
if current is None or previous is None:
|
|
2424
|
+
raise SyncError(f"rollback requires CURRENT and PREVIOUS for {tool}")
|
|
2425
|
+
verify_bundle(current, tool)
|
|
2426
|
+
verify_bundle(previous, tool)
|
|
2427
|
+
smoke_bundle(previous)
|
|
2428
|
+
production_root: Path | None = None
|
|
2429
|
+
production_previous: Path | None = None
|
|
2430
|
+
current_production_backup: Path | None = None
|
|
2431
|
+
production_verified: dict[str, Any] | None = None
|
|
2432
|
+
current_targets: dict[Path, Path] = {}
|
|
2433
|
+
if activate_production:
|
|
2434
|
+
if agents_root is None or hooks_dir is None:
|
|
2435
|
+
raise SyncError("production rollback requires agents_root and hooks_dir")
|
|
2436
|
+
production_root = state_root / "production"
|
|
2437
|
+
require_owned_directory(production_root)
|
|
2438
|
+
backups_root = ensure_owned_subdirectory(production_root, Path("backups"))
|
|
2439
|
+
production_previous = resolve_production_backup(
|
|
2440
|
+
production_root / "PREVIOUS", backups_root
|
|
2441
|
+
)
|
|
2442
|
+
current_targets, _ = production_target_sources(
|
|
2443
|
+
current,
|
|
2444
|
+
agents_root=agents_root,
|
|
2445
|
+
bin_dir=bin_dir,
|
|
2446
|
+
hooks_dir=hooks_dir,
|
|
2447
|
+
assert_installed_version=False,
|
|
2448
|
+
)
|
|
2449
|
+
previous_targets, _ = production_target_sources(
|
|
2450
|
+
previous,
|
|
2451
|
+
agents_root=agents_root,
|
|
2452
|
+
bin_dir=bin_dir,
|
|
2453
|
+
hooks_dir=hooks_dir,
|
|
2454
|
+
assert_installed_version=False,
|
|
2455
|
+
)
|
|
2456
|
+
retired = set(current_targets) - set(previous_targets)
|
|
2457
|
+
all_targets = tuple(set(current_targets) | set(previous_targets))
|
|
2458
|
+
if not any(p.exists() or p.is_symlink() for p in retired) and production_pair_matches(
|
|
2459
|
+
previous,
|
|
2460
|
+
agents_root=agents_root,
|
|
2461
|
+
bin_dir=bin_dir,
|
|
2462
|
+
hooks_dir=hooks_dir,
|
|
2463
|
+
):
|
|
2464
|
+
production_verified = verify_production_bundle(
|
|
2465
|
+
previous,
|
|
2466
|
+
agents_root=agents_root,
|
|
2467
|
+
bin_dir=bin_dir,
|
|
2468
|
+
hooks_dir=hooks_dir,
|
|
2469
|
+
)
|
|
2470
|
+
else:
|
|
2471
|
+
if production_previous is None:
|
|
2472
|
+
raise SyncError(f"production rollback has no previous pair for {tool}")
|
|
2473
|
+
verify_production_bundle(
|
|
2474
|
+
current, agents_root=agents_root, bin_dir=bin_dir, hooks_dir=hooks_dir
|
|
2475
|
+
)
|
|
2476
|
+
receipt = verify_production_backup(production_previous)
|
|
2477
|
+
if {Path(entry["target"]) for entry in receipt["entries"]} != set(all_targets):
|
|
2478
|
+
raise SyncError("production rollback backup does not cover both target sets")
|
|
2479
|
+
current_production_backup = capture_production_pair(
|
|
2480
|
+
tool, all_targets, production_root
|
|
2481
|
+
)
|
|
2482
|
+
try:
|
|
2483
|
+
restore_production_pair(production_previous, all_targets)
|
|
2484
|
+
production_verified = verify_production_bundle(
|
|
2485
|
+
previous,
|
|
2486
|
+
agents_root=agents_root,
|
|
2487
|
+
bin_dir=bin_dir,
|
|
2488
|
+
hooks_dir=hooks_dir,
|
|
2489
|
+
)
|
|
2490
|
+
except BaseException:
|
|
2491
|
+
restore_production_pair(
|
|
2492
|
+
current_production_backup, all_targets
|
|
2493
|
+
)
|
|
2494
|
+
raise
|
|
2495
|
+
try:
|
|
2496
|
+
atomic_symlink(state_root, "PREVIOUS", current)
|
|
2497
|
+
atomic_symlink(state_root, "CURRENT", previous)
|
|
2498
|
+
active = resolve_pointer(state_root / "CURRENT", bundles_root)
|
|
2499
|
+
verify_bundle(active or previous, tool)
|
|
2500
|
+
if production_root is not None and current_production_backup is not None:
|
|
2501
|
+
atomic_symlink(production_root, "PREVIOUS", current_production_backup)
|
|
2502
|
+
except BaseException:
|
|
2503
|
+
restore_pointer(state_root, "CURRENT", current)
|
|
2504
|
+
restore_pointer(state_root, "PREVIOUS", previous)
|
|
2505
|
+
if current_production_backup is not None:
|
|
2506
|
+
restore_production_pair(current_production_backup, all_targets)
|
|
2507
|
+
if production_root is not None:
|
|
2508
|
+
restore_pointer(production_root, "PREVIOUS", production_previous)
|
|
2509
|
+
raise
|
|
2510
|
+
return {
|
|
2511
|
+
"status": "ROLLED_BACK",
|
|
2512
|
+
"tool": tool,
|
|
2513
|
+
"current_bundle": previous.name,
|
|
2514
|
+
"previous_bundle": current.name,
|
|
2515
|
+
"production_activation": activate_production,
|
|
2516
|
+
"production_verified": production_verified,
|
|
2517
|
+
}
|
|
2518
|
+
|
|
2519
|
+
|
|
2520
|
+
SKILL_LINK_CLIENTS = ("claude", "cursor", "qoder", "qoder-cn")
|
|
2521
|
+
MANAGED_SKILL_NAMES = (SKILL_NAME, COMPATIBILITY_SKILL_NAME)
|
|
2522
|
+
|
|
2523
|
+
|
|
2524
|
+
def _validate_skill_frontmatter_and_refs(skill_root: Path) -> None:
|
|
2525
|
+
skill_md = skill_root / "SKILL.md"
|
|
2526
|
+
require_regular(skill_md, "canonical SKILL.md")
|
|
2527
|
+
content = skill_md.read_text(encoding="utf-8")
|
|
2528
|
+
frontmatter = re.match(r"\A---\n(.*?)\n---\n", content, re.DOTALL)
|
|
2529
|
+
if frontmatter is None:
|
|
2530
|
+
raise SyncError("invalid YAML frontmatter delimiters in SKILL.md")
|
|
2531
|
+
lines = [line for line in frontmatter.group(1).splitlines() if line.strip()]
|
|
2532
|
+
fields = [line.split(":", 1)[0].strip() for line in lines if ":" in line]
|
|
2533
|
+
if fields != ["name", "description"]:
|
|
2534
|
+
raise SyncError("SKILL.md frontmatter must contain only name and description")
|
|
2535
|
+
name = next((line.split(":", 1)[1].strip() for line in lines if line.startswith("name:")), "")
|
|
2536
|
+
description = next((line.split(":", 1)[1].strip() for line in lines if line.startswith("description:")), "")
|
|
2537
|
+
if name != SKILL_NAME or not description or len(description) > 1024 or "<" in description or ">" in description:
|
|
2538
|
+
raise SyncError("SKILL.md frontmatter name or description is invalid")
|
|
2539
|
+
if len(content.splitlines()) >= 500 or any(line.endswith((" ", "\t")) for line in content.splitlines()):
|
|
2540
|
+
raise SyncError("SKILL.md exceeds line limit or contains trailing whitespace")
|
|
2541
|
+
for rel in SKILL_PAYLOAD:
|
|
2542
|
+
if rel.startswith("references/") and f"]({rel})" not in content:
|
|
2543
|
+
raise SyncError(f"SKILL.md does not link required reference: {rel}")
|
|
2544
|
+
|
|
2545
|
+
|
|
2546
|
+
def _validate_skill_source(sources: Sources) -> tuple[str, str]:
|
|
2547
|
+
require_owned_directory(sources.skill_root)
|
|
2548
|
+
for rel in SKILL_PAYLOAD:
|
|
2549
|
+
p = sources.skill_root / rel
|
|
2550
|
+
require_owned_regular(p, "canonical Skill payload")
|
|
2551
|
+
mode = stat.S_IMODE(p.stat().st_mode)
|
|
2552
|
+
if mode & 0o111 or mode & 0o002:
|
|
2553
|
+
raise SyncError(f"unsafe canonical Skill file permissions: {p} ({mode:#05o})")
|
|
2554
|
+
_validate_skill_frontmatter_and_refs(sources.skill_root)
|
|
2555
|
+
require_owned_directory(sources.compatibility_skill_root)
|
|
2556
|
+
compat_md = sources.compatibility_skill_root / "SKILL.md"
|
|
2557
|
+
require_owned_regular(compat_md, "compatibility Skill")
|
|
2558
|
+
compat_text = compat_md.read_text(encoding="utf-8")
|
|
2559
|
+
for marker in ("name: three-tool-git-workflow", "Deprecated compatibility entry", f"${SKILL_NAME}"):
|
|
2560
|
+
if marker not in compat_text:
|
|
2561
|
+
raise SyncError("compatibility Skill does not point to canonical Skill")
|
|
2562
|
+
return tree_sha256(sources.skill_root, SKILL_PAYLOAD), sha256_file(compat_md)
|
|
2563
|
+
|
|
2564
|
+
|
|
2565
|
+
def _default_client_homes(home_dir: Path | None = None) -> dict[str, Path]:
|
|
2566
|
+
base = home_dir or Path.home()
|
|
2567
|
+
return {
|
|
2568
|
+
"codex": Path(os.environ.get("CODEX_HOME", base / ".codex")),
|
|
2569
|
+
"claude": Path(os.environ.get("CLAUDE_CONFIG_DIR", base / ".claude")),
|
|
2570
|
+
"gemini": Path(os.environ.get("GEMINI_HOME", base / ".gemini")),
|
|
2571
|
+
"cursor": Path(os.environ.get("CURSOR_HOME", base / ".cursor")),
|
|
2572
|
+
"qoder": Path(os.environ.get("QODER_HOME", base / ".qoder")),
|
|
2573
|
+
"qoder-cn": Path(os.environ.get("QODER_CN_HOME", base / ".qoder-cn")),
|
|
2574
|
+
}
|
|
2575
|
+
|
|
2576
|
+
|
|
2577
|
+
def _check_multi_client_skills(
|
|
2578
|
+
agents_root: Path,
|
|
2579
|
+
client_homes: dict[str, Path],
|
|
2580
|
+
) -> dict[str, Any]:
|
|
2581
|
+
shared_skills = agents_root / "skills"
|
|
2582
|
+
clients: dict[str, Any] = {}
|
|
2583
|
+
if (shared_skills / "synced").exists():
|
|
2584
|
+
raise SyncError("personal skill root contains disallowed account-synced directory: skills/synced")
|
|
2585
|
+
|
|
2586
|
+
# Codex reads ~/.agents/skills directly and adds no duplicate symlinks under ~/.codex/skills.
|
|
2587
|
+
codex_dir = client_homes["codex"]
|
|
2588
|
+
codex_dup = [
|
|
2589
|
+
name for name in MANAGED_SKILL_NAMES
|
|
2590
|
+
if (codex_dir / "skills" / name).exists() or (codex_dir / "skills" / name).is_symlink()
|
|
2591
|
+
]
|
|
2592
|
+
clients["codex"] = {
|
|
2593
|
+
"present": codex_dir.is_dir(),
|
|
2594
|
+
"uses_shared_root": True,
|
|
2595
|
+
"duplicate_links": codex_dup,
|
|
2596
|
+
"status": "FAIL" if codex_dup else "PASS",
|
|
2597
|
+
}
|
|
2598
|
+
|
|
2599
|
+
for cname in SKILL_LINK_CLIENTS:
|
|
2600
|
+
cdir = client_homes[cname]
|
|
2601
|
+
if not cdir.is_dir():
|
|
2602
|
+
clients[cname] = {"present": False, "status": "SKIP"}
|
|
2603
|
+
continue
|
|
2604
|
+
cskills = cdir / "skills"
|
|
2605
|
+
if cskills.is_symlink() and cskills.resolve(strict=False) == shared_skills.resolve(strict=False):
|
|
2606
|
+
clients[cname] = {
|
|
2607
|
+
"present": True,
|
|
2608
|
+
"status": "FAIL",
|
|
2609
|
+
"error": f"{cname} uses a whole-root symlink to ~/.agents/skills instead of per-Skill links",
|
|
2610
|
+
}
|
|
2611
|
+
continue
|
|
2612
|
+
exposed: dict[str, bool] = {}
|
|
2613
|
+
for sname in MANAGED_SKILL_NAMES:
|
|
2614
|
+
link = cskills / sname
|
|
2615
|
+
target = shared_skills / sname
|
|
2616
|
+
exposed[sname] = link.exists() and link.resolve(strict=False) == target.resolve(strict=False)
|
|
2617
|
+
clients[cname] = {
|
|
2618
|
+
"present": True,
|
|
2619
|
+
"per_skill_links": exposed,
|
|
2620
|
+
"status": "PASS" if all(exposed.values()) else "DRIFT",
|
|
2621
|
+
}
|
|
2622
|
+
|
|
2623
|
+
gemini_dir = client_homes["gemini"]
|
|
2624
|
+
if not gemini_dir.is_dir():
|
|
2625
|
+
clients["gemini"] = {"present": False, "status": "SKIP"}
|
|
2626
|
+
else:
|
|
2627
|
+
cfg_path = gemini_dir / "config" / "skills.json"
|
|
2628
|
+
if not cfg_path.is_file():
|
|
2629
|
+
clients["gemini"] = {"present": True, "config": str(cfg_path), "status": "DRIFT"}
|
|
2630
|
+
else:
|
|
2631
|
+
try:
|
|
2632
|
+
cfg_data = json.loads(cfg_path.read_text(encoding="utf-8"))
|
|
2633
|
+
except (OSError, ValueError):
|
|
2634
|
+
clients["gemini"] = {"present": True, "config": str(cfg_path), "status": "FAIL"}
|
|
2635
|
+
else:
|
|
2636
|
+
expected_roots = {str(shared_skills), str(shared_skills / SKILL_NAME)}
|
|
2637
|
+
recorded: set[str] = set()
|
|
2638
|
+
if isinstance(cfg_data, dict):
|
|
2639
|
+
for key in ("paths", "skillPaths", "skills"):
|
|
2640
|
+
val = cfg_data.get(key)
|
|
2641
|
+
if isinstance(val, list):
|
|
2642
|
+
recorded.update(str(v) for v in val if isinstance(v, str))
|
|
2643
|
+
clients["gemini"] = {
|
|
2644
|
+
"present": True,
|
|
2645
|
+
"config": str(cfg_path),
|
|
2646
|
+
"registered_paths": sorted(recorded & expected_roots),
|
|
2647
|
+
"status": "PASS" if (recorded & expected_roots) else "DRIFT",
|
|
2648
|
+
}
|
|
2649
|
+
return clients
|
|
2650
|
+
|
|
2651
|
+
|
|
2652
|
+
def skill_check(
|
|
2653
|
+
sources: Sources,
|
|
2654
|
+
*,
|
|
2655
|
+
agents_root: Path,
|
|
2656
|
+
client_homes: dict[str, Path] | None = None,
|
|
2657
|
+
) -> dict[str, Any]:
|
|
2658
|
+
canonical_sha, compat_sha = _validate_skill_source(sources)
|
|
2659
|
+
installed_sha, installed_compat_sha = installed_skill_hashes(agents_root)
|
|
2660
|
+
homes = _default_client_homes() if client_homes is None else client_homes
|
|
2661
|
+
clients = _check_multi_client_skills(agents_root, homes)
|
|
2662
|
+
trusted = (
|
|
2663
|
+
installed_sha in (None, canonical_sha)
|
|
2664
|
+
or installed_sha in RELEASED_CANONICAL_SKILL_SHA256
|
|
2665
|
+
)
|
|
2666
|
+
payload_match = installed_sha == canonical_sha and installed_compat_sha == compat_sha
|
|
2667
|
+
return {
|
|
2668
|
+
"schema_version": SCHEMA_VERSION,
|
|
2669
|
+
"operation": "skill-check",
|
|
2670
|
+
"status": "PASS" if (payload_match and trusted) else ("DRIFT" if trusted else "FAIL"),
|
|
2671
|
+
"source_skill_sha256": canonical_sha,
|
|
2672
|
+
"source_compatibility_sha256": compat_sha,
|
|
2673
|
+
"installed_skill_sha256": installed_sha,
|
|
2674
|
+
"installed_compatibility_sha256": installed_compat_sha,
|
|
2675
|
+
"trusted_lineage": trusted,
|
|
2676
|
+
"clients": clients,
|
|
2677
|
+
}
|
|
2678
|
+
|
|
2679
|
+
|
|
2680
|
+
def _sync_multi_client_skills(
|
|
2681
|
+
agents_root: Path,
|
|
2682
|
+
client_homes: dict[str, Path],
|
|
2683
|
+
) -> dict[str, Any]:
|
|
2684
|
+
shared_skills = agents_root / "skills"
|
|
2685
|
+
require_owned_directory(shared_skills)
|
|
2686
|
+
if (shared_skills / "synced").exists():
|
|
2687
|
+
raise SyncError("refusing to sync while skills/synced exists inside shared personal root")
|
|
2688
|
+
results: dict[str, Any] = {}
|
|
2689
|
+
|
|
2690
|
+
for cname in SKILL_LINK_CLIENTS:
|
|
2691
|
+
cdir = client_homes[cname]
|
|
2692
|
+
if not cdir.is_dir():
|
|
2693
|
+
results[cname] = {"status": "SKIP"}
|
|
2694
|
+
continue
|
|
2695
|
+
cskills = cdir / "skills"
|
|
2696
|
+
if cskills.is_symlink():
|
|
2697
|
+
if cskills.resolve(strict=False) == shared_skills.resolve(strict=False):
|
|
2698
|
+
raise SyncError(f"{cname} skills directory must not symlink whole shared root")
|
|
2699
|
+
raise SyncError(f"{cname} skills directory is an unsafe symlink: {cskills}")
|
|
2700
|
+
require_owned_directory(cskills, create=True)
|
|
2701
|
+
linked: list[str] = []
|
|
2702
|
+
for sname in MANAGED_SKILL_NAMES:
|
|
2703
|
+
link_path = cskills / sname
|
|
2704
|
+
target = shared_skills / sname
|
|
2705
|
+
if link_path.is_symlink():
|
|
2706
|
+
if link_path.resolve(strict=False) == target.resolve(strict=False):
|
|
2707
|
+
linked.append(sname)
|
|
2708
|
+
continue
|
|
2709
|
+
link_path.unlink()
|
|
2710
|
+
elif link_path.exists():
|
|
2711
|
+
raise SyncError(f"{cname} already has non-symlink skill at {link_path}; preserve manually")
|
|
2712
|
+
os.symlink(str(target), link_path)
|
|
2713
|
+
linked.append(sname)
|
|
2714
|
+
results[cname] = {"status": "SYNCED", "linked": linked}
|
|
2715
|
+
|
|
2716
|
+
gemini_dir = client_homes["gemini"]
|
|
2717
|
+
if not gemini_dir.is_dir():
|
|
2718
|
+
results["gemini"] = {"status": "SKIP"}
|
|
2719
|
+
else:
|
|
2720
|
+
cfg_dir = ensure_owned_subdirectory(gemini_dir, Path("config"))
|
|
2721
|
+
cfg_path = cfg_dir / "skills.json"
|
|
2722
|
+
if cfg_path.is_symlink():
|
|
2723
|
+
raise SyncError(f"unsafe Gemini config symlink: {cfg_path}")
|
|
2724
|
+
if cfg_path.exists():
|
|
2725
|
+
try:
|
|
2726
|
+
cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
|
|
2727
|
+
except (OSError, ValueError) as exc:
|
|
2728
|
+
raise SyncError(f"invalid existing Gemini skills.json: {exc}") from exc
|
|
2729
|
+
if not isinstance(cfg, dict):
|
|
2730
|
+
raise SyncError("Gemini skills.json root must be an object")
|
|
2731
|
+
else:
|
|
2732
|
+
cfg = {}
|
|
2733
|
+
key = "paths" if "paths" in cfg or "skillPaths" not in cfg else "skillPaths"
|
|
2734
|
+
existing = cfg.get(key)
|
|
2735
|
+
if existing is None:
|
|
2736
|
+
entries: list[str] = []
|
|
2737
|
+
elif isinstance(existing, list) and all(isinstance(x, str) for x in existing):
|
|
2738
|
+
entries = list(existing)
|
|
2739
|
+
else:
|
|
2740
|
+
raise SyncError(f"Gemini skills.json field {key} must be a list of strings")
|
|
2741
|
+
shared_str = str(shared_skills)
|
|
2742
|
+
if shared_str not in entries:
|
|
2743
|
+
entries.append(shared_str)
|
|
2744
|
+
cfg[key] = entries
|
|
2745
|
+
write_json(cfg_path, cfg, mode=0o600)
|
|
2746
|
+
results["gemini"] = {"status": "SYNCED", "config": str(cfg_path), "registered": shared_str}
|
|
2747
|
+
|
|
2748
|
+
codex_dir = client_homes["codex"]
|
|
2749
|
+
results["codex"] = {"status": "NATIVE", "shared_root": str(shared_skills), "present": codex_dir.is_dir()}
|
|
2750
|
+
return results
|
|
2751
|
+
|
|
2752
|
+
|
|
2753
|
+
def skill_install(
|
|
2754
|
+
sources: Sources,
|
|
2755
|
+
*,
|
|
2756
|
+
agents_root: Path,
|
|
2757
|
+
client_homes: dict[str, Path] | None = None,
|
|
2758
|
+
sync_clients: bool = True,
|
|
2759
|
+
) -> dict[str, Any]:
|
|
2760
|
+
canonical_sha, compat_sha = _validate_skill_source(sources)
|
|
2761
|
+
require_owned_directory(agents_root, create=True)
|
|
2762
|
+
skills_root = ensure_owned_subdirectory(agents_root, Path("skills"))
|
|
2763
|
+
if (skills_root / "synced").exists():
|
|
2764
|
+
raise SyncError("refusing installation while skills/synced exists inside shared root")
|
|
2765
|
+
with deployment_lock(skills_root):
|
|
2766
|
+
live_canonical = skills_root / SKILL_NAME
|
|
2767
|
+
if live_canonical.exists():
|
|
2768
|
+
if live_canonical.is_symlink():
|
|
2769
|
+
raise SyncError(f"live Skill target is a symlink: {live_canonical}")
|
|
2770
|
+
installed_sha, _ = installed_skill_hashes(agents_root)
|
|
2771
|
+
if installed_sha not in (canonical_sha, None) and installed_sha not in RELEASED_CANONICAL_SKILL_SHA256:
|
|
2772
|
+
raise SyncError("unknown content drift in live Skill; preserve before installing")
|
|
2773
|
+
|
|
2774
|
+
stage_root = Path(tempfile.mkdtemp(prefix=".skill-stage-", dir=skills_root))
|
|
2775
|
+
try:
|
|
2776
|
+
copy_skill_payload(sources.skill_root, stage_root / SKILL_NAME)
|
|
2777
|
+
copy_compatibility_skill(sources.compatibility_skill_root, stage_root)
|
|
2778
|
+
canon_target = ensure_owned_subdirectory(skills_root, Path(SKILL_NAME))
|
|
2779
|
+
for rel in SKILL_PAYLOAD:
|
|
2780
|
+
dest = canon_target / rel
|
|
2781
|
+
ensure_owned_subdirectory(canon_target, Path(rel).parent)
|
|
2782
|
+
if dest.is_symlink():
|
|
2783
|
+
raise SyncError(f"live target file is a symlink: {dest}")
|
|
2784
|
+
shutil.copyfile(sources.skill_root / rel, dest)
|
|
2785
|
+
dest.chmod(0o600)
|
|
2786
|
+
compat_dir = ensure_owned_subdirectory(skills_root, Path(COMPATIBILITY_SKILL_NAME))
|
|
2787
|
+
compat_dest = compat_dir / "SKILL.md"
|
|
2788
|
+
if compat_dest.is_symlink():
|
|
2789
|
+
raise SyncError(f"live compatibility target is a symlink: {compat_dest}")
|
|
2790
|
+
shutil.copyfile(sources.compatibility_skill_root / "SKILL.md", compat_dest)
|
|
2791
|
+
compat_dest.chmod(0o600)
|
|
2792
|
+
finally:
|
|
2793
|
+
if stage_root.exists():
|
|
2794
|
+
shutil.rmtree(stage_root)
|
|
2795
|
+
|
|
2796
|
+
homes = _default_client_homes() if client_homes is None else client_homes
|
|
2797
|
+
clients = _sync_multi_client_skills(agents_root, homes) if sync_clients else {}
|
|
2798
|
+
|
|
2799
|
+
installed_sha, installed_compat_sha = installed_skill_hashes(agents_root)
|
|
2800
|
+
if installed_sha != canonical_sha or installed_compat_sha != compat_sha:
|
|
2801
|
+
raise SyncError("post-install Skill payload hash verification failed")
|
|
2802
|
+
return {
|
|
2803
|
+
"schema_version": SCHEMA_VERSION,
|
|
2804
|
+
"operation": "skill-install",
|
|
2805
|
+
"status": "INSTALLED",
|
|
2806
|
+
"skill_sha256": installed_sha,
|
|
2807
|
+
"compatibility_skill_sha256": installed_compat_sha,
|
|
2808
|
+
"clients": clients,
|
|
2809
|
+
}
|
|
2810
|
+
|
|
2811
|
+
|
|
2812
|
+
def _default_source_root(repo: Path | None = None) -> Path:
|
|
2813
|
+
env_root = os.environ.get("TOOL_SKILL_SYNC_SOURCE_ROOT", "").strip()
|
|
2814
|
+
if env_root:
|
|
2815
|
+
return Path(env_root).expanduser()
|
|
2816
|
+
resolved_file = Path(__file__).resolve()
|
|
2817
|
+
for depth in (2, 3):
|
|
2818
|
+
if len(resolved_file.parents) > depth:
|
|
2819
|
+
checkout_root = resolved_file.parents[depth]
|
|
2820
|
+
if (checkout_root / "toolchain_compatibility.json").is_file():
|
|
2821
|
+
return checkout_root.parent
|
|
2822
|
+
if repo is not None:
|
|
2823
|
+
candidate = repo.resolve(strict=False)
|
|
2824
|
+
for parent in (candidate, *candidate.parents):
|
|
2825
|
+
if (parent / "toolchain_compatibility.json").is_file():
|
|
2826
|
+
return parent.parent
|
|
2827
|
+
projects_root = Path.home() / "projects"
|
|
2828
|
+
if (projects_root / "git-finalizer" / "toolchain_compatibility.json").is_file():
|
|
2829
|
+
return projects_root
|
|
2830
|
+
cwd = Path.cwd().resolve(strict=False)
|
|
2831
|
+
for parent in (cwd, *cwd.parents):
|
|
2832
|
+
if (parent / "toolchain_compatibility.json").is_file():
|
|
2833
|
+
return parent.parent
|
|
2834
|
+
return projects_root
|
|
2835
|
+
|
|
2836
|
+
|
|
2837
|
+
def parser() -> argparse.ArgumentParser:
|
|
2838
|
+
result = argparse.ArgumentParser(prog="tool-skill-sync")
|
|
2839
|
+
result.add_argument("--version", action="version", version=f"%(prog)s {VERSION}")
|
|
2840
|
+
result.add_argument("--source-root", type=Path, default=_default_source_root())
|
|
2841
|
+
result.add_argument(
|
|
2842
|
+
"--source-repo", action="append", default=[], metavar="TOOL=PATH",
|
|
2843
|
+
help="explicit source checkout; repeat for independently allocated worktrees",
|
|
2844
|
+
)
|
|
2845
|
+
result.add_argument(
|
|
2846
|
+
"--install-root",
|
|
2847
|
+
type=Path,
|
|
2848
|
+
default=Path.home() / ".local" / "state" / "tool-skill-sync",
|
|
2849
|
+
)
|
|
2850
|
+
result.add_argument(
|
|
2851
|
+
"--source-ref", action="append", default=[], metavar="TOOL=FULL_COMMIT_OID",
|
|
2852
|
+
help="read released Python package metadata from an exact commit without touching its checkout",
|
|
2853
|
+
)
|
|
2854
|
+
result.add_argument("--agents-root", type=Path, default=Path.home() / ".agents")
|
|
2855
|
+
result.add_argument("--bin-dir", type=Path)
|
|
2856
|
+
result.add_argument(
|
|
2857
|
+
"--hooks-dir", type=Path, default=Path.home() / ".agents" / "hooks"
|
|
2858
|
+
)
|
|
2859
|
+
subcommands = result.add_subparsers(dest="command", required=True)
|
|
2860
|
+
subcommands.add_parser("status")
|
|
2861
|
+
for sname in ("skill-check", "skill-install"):
|
|
2862
|
+
sp = subcommands.add_parser(sname)
|
|
2863
|
+
sp.add_argument("--codex-home", type=Path)
|
|
2864
|
+
sp.add_argument("--claude-home", type=Path)
|
|
2865
|
+
sp.add_argument("--gemini-home", type=Path)
|
|
2866
|
+
sp.add_argument("--cursor-home", type=Path)
|
|
2867
|
+
sp.add_argument("--qoder-home", type=Path)
|
|
2868
|
+
if sname == "skill-install":
|
|
2869
|
+
sp.add_argument("--no-sync-clients", action="store_true")
|
|
2870
|
+
doctor_parser = subcommands.add_parser(
|
|
2871
|
+
"doctor", help="read-only toolchain deployment and instruction freshness check"
|
|
2872
|
+
)
|
|
2873
|
+
doctor_parser.add_argument("--repo", type=Path)
|
|
2874
|
+
doctor_parser.add_argument("--summary", action="store_true")
|
|
2875
|
+
doctor_parser.add_argument("--previous-fingerprint")
|
|
2876
|
+
doctor_parser.add_argument(
|
|
2877
|
+
"--codex-home",
|
|
2878
|
+
type=Path,
|
|
2879
|
+
default=Path(os.environ.get("CODEX_HOME", Path.home() / ".codex")),
|
|
2880
|
+
)
|
|
2881
|
+
doctor_parser.add_argument(
|
|
2882
|
+
"--claude-home",
|
|
2883
|
+
type=Path,
|
|
2884
|
+
default=Path(os.environ.get("CLAUDE_CONFIG_DIR", Path.home() / ".claude")),
|
|
2885
|
+
)
|
|
2886
|
+
doctor_parser.add_argument("--controller", type=Path)
|
|
2887
|
+
doctor_parser.add_argument("--controller-source", type=Path)
|
|
2888
|
+
doctor_parser.add_argument(
|
|
2889
|
+
"--controller-runtime-root",
|
|
2890
|
+
type=Path,
|
|
2891
|
+
default=Path.home() / ".local/share/worktree-controller",
|
|
2892
|
+
)
|
|
2893
|
+
check_parser = subcommands.add_parser("check")
|
|
2894
|
+
check_parser.add_argument("tool")
|
|
2895
|
+
check_parser.add_argument(
|
|
2896
|
+
"--source-only",
|
|
2897
|
+
action="store_true",
|
|
2898
|
+
help=(
|
|
2899
|
+
"validate only the canonical source contract and skip installed-production "
|
|
2900
|
+
"drift detection (for build environments with no installation)"
|
|
2901
|
+
),
|
|
2902
|
+
)
|
|
2903
|
+
install_parser = subcommands.add_parser("install")
|
|
2904
|
+
install_parser.add_argument("tool")
|
|
2905
|
+
install_parser.add_argument("--allow-dirty-source", action="store_true")
|
|
2906
|
+
install_parser.add_argument("--activate-production", action="store_true")
|
|
2907
|
+
upgrade_parser = subcommands.add_parser("upgrade")
|
|
2908
|
+
upgrade_parser.add_argument("tool")
|
|
2909
|
+
upgrade_parser.add_argument("--dry-run", action="store_true")
|
|
2910
|
+
upgrade_parser.add_argument(
|
|
2911
|
+
"--previous-bundle",
|
|
2912
|
+
type=Path,
|
|
2913
|
+
help="verified prior release identity when all console-script names changed",
|
|
2914
|
+
)
|
|
2915
|
+
rollback_parser = subcommands.add_parser("rollback")
|
|
2916
|
+
rollback_parser.add_argument("tool")
|
|
2917
|
+
rollback_parser.add_argument("--activate-production", action="store_true")
|
|
2918
|
+
return result
|
|
2919
|
+
|
|
2920
|
+
|
|
2921
|
+
def main(arguments: Sequence[str] | None = None) -> int:
|
|
2922
|
+
raw_argv = list(sys.argv[1:] if arguments is None else arguments)
|
|
2923
|
+
args = parser().parse_args(raw_argv)
|
|
2924
|
+
explicit_source_root = any(
|
|
2925
|
+
tok == "--source-root" or tok.startswith("--source-root=") for tok in raw_argv
|
|
2926
|
+
)
|
|
2927
|
+
source_root = args.source_root
|
|
2928
|
+
if (
|
|
2929
|
+
not explicit_source_root
|
|
2930
|
+
and getattr(args, "repo", None) is not None
|
|
2931
|
+
and not (source_root / "git-finalizer" / "toolchain_compatibility.json").is_file()
|
|
2932
|
+
):
|
|
2933
|
+
source_root = _default_source_root(repo=args.repo)
|
|
2934
|
+
try:
|
|
2935
|
+
source_repos = {}
|
|
2936
|
+
for value in args.source_repo:
|
|
2937
|
+
name, separator, path = value.partition("=")
|
|
2938
|
+
if not separator or not SAFE_NAME.fullmatch(name) or not Path(path).is_absolute():
|
|
2939
|
+
raise SyncError("source-repo requires TOOL=/absolute/path")
|
|
2940
|
+
if name in source_repos:
|
|
2941
|
+
raise SyncError("source-repo contains a duplicate tool")
|
|
2942
|
+
source_repos[name] = Path(path)
|
|
2943
|
+
source_refs = {}
|
|
2944
|
+
for value in args.source_ref:
|
|
2945
|
+
name, separator, oid = value.partition("=")
|
|
2946
|
+
if not separator or not SAFE_NAME.fullmatch(name) or not FULL_GIT_OID.fullmatch(oid):
|
|
2947
|
+
raise SyncError("source-ref requires TOOL=FULL_COMMIT_OID")
|
|
2948
|
+
if name in source_refs:
|
|
2949
|
+
raise SyncError("source-ref contains a duplicate tool")
|
|
2950
|
+
source_refs[name] = oid
|
|
2951
|
+
sources = Sources(source_root, source_repos, source_refs)
|
|
2952
|
+
if args.command in {"skill-check", "skill-install"}:
|
|
2953
|
+
homes = _default_client_homes()
|
|
2954
|
+
for key, attr in (
|
|
2955
|
+
("codex", "codex_home"),
|
|
2956
|
+
("claude", "claude_home"),
|
|
2957
|
+
("gemini", "gemini_home"),
|
|
2958
|
+
("cursor", "cursor_home"),
|
|
2959
|
+
("qoder", "qoder_home"),
|
|
2960
|
+
):
|
|
2961
|
+
val = getattr(args, attr, None)
|
|
2962
|
+
if val is not None:
|
|
2963
|
+
homes[key] = val.resolve()
|
|
2964
|
+
if args.command == "skill-check":
|
|
2965
|
+
output = skill_check(sources, agents_root=args.agents_root.resolve(), client_homes=homes)
|
|
2966
|
+
print(canonical_json(output).decode(), end="")
|
|
2967
|
+
return 0 if output["status"] == "PASS" else 1
|
|
2968
|
+
output = skill_install(
|
|
2969
|
+
sources,
|
|
2970
|
+
agents_root=args.agents_root.resolve(),
|
|
2971
|
+
client_homes=homes,
|
|
2972
|
+
sync_clients=not args.no_sync_clients,
|
|
2973
|
+
)
|
|
2974
|
+
print(canonical_json(output).decode(), end="")
|
|
2975
|
+
return 0
|
|
2976
|
+
if args.command == "doctor":
|
|
2977
|
+
from . import workflow_health
|
|
2978
|
+
output = workflow_health.doctor(
|
|
2979
|
+
sources,
|
|
2980
|
+
agents_root=args.agents_root.resolve(),
|
|
2981
|
+
bin_dir=args.bin_dir,
|
|
2982
|
+
hooks_dir=args.hooks_dir.resolve(),
|
|
2983
|
+
repo=args.repo,
|
|
2984
|
+
codex_home=args.codex_home.resolve(),
|
|
2985
|
+
controller=args.controller,
|
|
2986
|
+
claude_home=args.claude_home.resolve(),
|
|
2987
|
+
controller_runtime_root=args.controller_runtime_root,
|
|
2988
|
+
controller_source=args.controller_source or source_root / "worktree-controller",
|
|
2989
|
+
previous_fingerprint=args.previous_fingerprint,
|
|
2990
|
+
)
|
|
2991
|
+
print(canonical_json(workflow_health.summary(output) if args.summary else output).decode(), end="")
|
|
2992
|
+
return 0 if output["status"] == "PASS" else 1
|
|
2993
|
+
if args.command == "status":
|
|
2994
|
+
output = status(sources, args.agents_root.resolve(), args.bin_dir)
|
|
2995
|
+
else:
|
|
2996
|
+
if args.tool not in sources.names():
|
|
2997
|
+
raise SyncError(f"unknown tool: {args.tool}")
|
|
2998
|
+
if args.command == "check":
|
|
2999
|
+
output = (
|
|
3000
|
+
check_tool(sources, args.tool)
|
|
3001
|
+
if args.source_only
|
|
3002
|
+
else check_tool_deployment(
|
|
3003
|
+
sources,
|
|
3004
|
+
args.tool,
|
|
3005
|
+
args.agents_root.resolve(),
|
|
3006
|
+
args.bin_dir,
|
|
3007
|
+
args.hooks_dir.resolve(),
|
|
3008
|
+
)
|
|
3009
|
+
)
|
|
3010
|
+
print(canonical_json(output).decode(), end="")
|
|
3011
|
+
return 0 if output["status"] == "PASS" else 1
|
|
3012
|
+
if args.command == "upgrade":
|
|
3013
|
+
output = upgrade(
|
|
3014
|
+
sources,
|
|
3015
|
+
args.tool,
|
|
3016
|
+
bin_dir=args.bin_dir,
|
|
3017
|
+
dry_run=args.dry_run,
|
|
3018
|
+
previous_bundle=args.previous_bundle,
|
|
3019
|
+
)
|
|
3020
|
+
print(canonical_json(output).decode(), end="")
|
|
3021
|
+
return 0
|
|
3022
|
+
if args.command == "install":
|
|
3023
|
+
output = install(
|
|
3024
|
+
sources,
|
|
3025
|
+
args.tool,
|
|
3026
|
+
args.install_root.resolve(),
|
|
3027
|
+
allow_dirty_source=args.allow_dirty_source,
|
|
3028
|
+
activate_production=args.activate_production,
|
|
3029
|
+
agents_root=args.agents_root.resolve(),
|
|
3030
|
+
bin_dir=args.bin_dir.resolve() if args.bin_dir else None,
|
|
3031
|
+
hooks_dir=args.hooks_dir.resolve(),
|
|
3032
|
+
)
|
|
3033
|
+
else:
|
|
3034
|
+
output = rollback(
|
|
3035
|
+
args.tool,
|
|
3036
|
+
args.install_root.resolve(),
|
|
3037
|
+
activate_production=args.activate_production,
|
|
3038
|
+
agents_root=args.agents_root.resolve(),
|
|
3039
|
+
bin_dir=args.bin_dir.resolve() if args.bin_dir else None,
|
|
3040
|
+
hooks_dir=args.hooks_dir.resolve(),
|
|
3041
|
+
)
|
|
3042
|
+
print(canonical_json(output).decode(), end="")
|
|
3043
|
+
return 0
|
|
3044
|
+
except (OSError, SyncError, subprocess.SubprocessError) as exc:
|
|
3045
|
+
print(f"tool-skill-sync: {exc}", file=sys.stderr)
|
|
3046
|
+
return 2
|
|
3047
|
+
|
|
3048
|
+
|
|
3049
|
+
if __name__ == "__main__":
|
|
3050
|
+
raise SystemExit(main())
|