convergent-cli 0.1.0__py3-none-any.whl

convergent_cli/skill_files/convergent-verify/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: convergent-verify
+description: Inspect one Convergent recording and report evidence-backed instrumentation findings without changing code. Use when a user asks to verify, inspect, debug, or explain Convergent spans, or when convergent-instrument needs to compare a run with its expected recording.
+version: 2
+---
+
+# Load the current verification workflow
+
+If `read_docs` is available, call it for `/agent-skills/verify`.
+If the tool is unavailable or the call fails, run `cv docs read /agent-skills/verify`.
+Then follow that page.
+
+If `cv` fails with `login_required`, ask the user to run `cv login`, then retry once.
+Stop on any other `cv docs read` failure. Do not use GitHub, repository prose, or a bundled copy as
+documentation fallback.

convergent_cli/skills.py

@@ -0,0 +1,489 @@
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import re
+import secrets
+import stat
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import NoReturn, cast
+
+from convergent_cli.errors import ApiError
+
+SKILL_FILES_DIR = Path(__file__).parent / "skill_files"
+
+RECEIPT_NAME = ".convergent-skills.json"
+
+# Skills an earlier cv installed that `convergent` now replaces. Their receipt
+# entries stay readable so install can remove the files it wrote.
+RETIRED_SKILLS = frozenset({"convergent-cv", "convergent-mcp"})
+
+_RECEIPT_SCHEMA_VERSION = 1
+_RECEIPT_OBJECT = "cv.skills_receipt"
+
+_SKILL_NAME = re.compile(r"[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?")
+_SHA256 = re.compile(r"[0-9a-f]{64}")
+
+CLAUDE_SKILLS = Path(".claude") / "skills"
+AGENTS_SKILLS = Path(".agents") / "skills"
+
+
+class SkillError(ApiError):
+    def __init__(self, message: str, fix: str | None = None) -> None:
+        super().__init__(message)
+        self.fix = fix
+
+
+@dataclass(frozen=True, slots=True)
+class PackagedSkill:
+    name: str
+    version: str
+    description: str
+    path: Path
+
+    def read(self) -> bytes:
+        return self.path.read_bytes()
+
+
+@dataclass(frozen=True, slots=True)
+class InstallReport:
+    target: Path
+    installed: list[dict[str, str]]
+    unchanged: list[dict[str, str]]
+    skipped: list[dict[str, str]]
+    removed: list[str]
+
+    @property
+    def usable(self) -> bool:
+        return bool(self.installed or self.unchanged)
+
+
+def catalog() -> list[PackagedSkill]:
+    found: list[PackagedSkill] = []
+    for path in sorted(SKILL_FILES_DIR.glob("*/SKILL.md")):
+        fields = _frontmatter(path.read_text(encoding="utf-8"))
+        name = fields.get("name", "")
+        if name != path.parent.name or _SKILL_NAME.fullmatch(name) is None:
+            raise ValueError(f"{path} must name its safe parent directory")
+        found.append(
+            PackagedSkill(
+                name=name,
+                version=fields.get("version", "1"),
+                description=fields.get("description", ""),
+                path=path,
+            )
+        )
+    return found
+
+
+def install(target: Path, *, force: bool = False) -> InstallReport:
+    selected = catalog()
+    try:
+        prepared = [
+            (skill, contents, _digest(contents))
+            for skill in selected
+            for contents in (skill.read(),)
+        ]
+    except OSError as error:
+        raise SkillError(
+            f"this cv installation could not read its skill files: {error}",
+            fix="Reinstall or upgrade cv, then run the command again.",
+        ) from error
+
+    installed: list[dict[str, str]] = []
+    unchanged: list[dict[str, str]] = []
+    skipped: list[dict[str, str]] = []
+    removed: list[str] = []
+    replaced: list[tuple[Path, bytes | None, int | None, str, tuple[int, int]]] = []
+    unlinked: list[tuple[Path, bytes, int]] = []
+
+    try:
+        _make_directories(target)
+        written = read_receipt(target)
+        removable, blocked = retirements(target, written, force=force)
+        skipped.extend(blocked)
+        for skill, contents, desired in prepared:
+            relative = f"{skill.name}/SKILL.md"
+            destination = target / relative
+            problem = _destination_problem(target, destination)
+            if problem is not None:
+                skipped.append({"name": skill.name, "path": str(destination), "reason": problem})
+                continue
+            recorded = written.get(relative)
+            try:
+                previous, previous_node = _read_regular(destination)
+            except FileNotFoundError:
+                previous, previous_node = None, None
+            reason = _reason_to_skip(previous, recorded, desired, force=force)
+            if reason is _UNCHANGED:
+                unchanged.append(
+                    {"name": skill.name, "version": skill.version, "path": str(destination)}
+                )
+                continue
+            if reason is not None:
+                skipped.append({"name": skill.name, "path": str(destination), "reason": reason})
+                continue
+            previous_mode = (
+                stat.S_IMODE(previous_node.st_mode) if previous_node is not None else None
+            )
+            _make_directories(destination.parent)
+            identity = _atomic_write(destination, contents, mode=0o644)
+            replaced.append((destination, previous, previous_mode, desired, identity))
+            written[relative] = {
+                "path": relative,
+                "name": skill.name,
+                "version": skill.version,
+                "sha256": desired,
+                "cv_version": _cli_version(),
+                "installed_at": datetime.now(UTC).isoformat(),
+            }
+            installed.append(
+                {"name": skill.name, "version": skill.version, "path": str(destination)}
+            )
+        for name in removable:
+            destination = target / name / "SKILL.md"
+            try:
+                previous, previous_node = _read_regular(destination)
+            except FileNotFoundError:
+                pass
+            else:
+                destination.unlink()
+                unlinked.append((destination, previous, stat.S_IMODE(previous_node.st_mode)))
+                with contextlib.suppress(OSError):
+                    destination.parent.rmdir()
+            del written[f"{name}/SKILL.md"]
+            removed.append(name)
+        if installed or removed:
+            _write_receipt(target, written)
+    except BaseException as error:
+        failures = _restore_replaced(replaced) + _restore_unlinked(unlinked)
+        if isinstance(error, SkillError):
+            raise
+        if not isinstance(error, OSError | ValueError):
+            raise
+        rollback = (
+            f" Rollback also failed for: {'; '.join(failures)}."
+            if failures
+            else " Prior files were restored."
+        )
+        raise SkillError(
+            f"could not install into {target}: {error}. Nothing was claimed installed.{rollback}"
+        ) from error
+
+    return InstallReport(target, installed, unchanged, skipped, removed)
+
+
+def retirements(
+    target: Path, written: dict[str, dict[str, str]], *, force: bool
+) -> tuple[list[str], list[dict[str, str]]]:
+    """Retired skills whose files cv wrote and may delete, and those left in place."""
+    removable: list[str] = []
+    blocked: list[dict[str, str]] = []
+    for name in sorted(RETIRED_SKILLS):
+        relative = f"{name}/SKILL.md"
+        destination = target / relative
+        problem = _destination_problem(target, destination)
+        if problem is not None:
+            blocked.append({"name": name, "path": str(destination), "reason": problem})
+            continue
+        try:
+            previous, _node = _read_regular(destination)
+        except FileNotFoundError:
+            if relative in written:
+                removable.append(name)
+            continue
+        recorded = written.get(relative)
+        desired = recorded.get("sha256", "") if recorded is not None else ""
+        reason = _reason_to_skip(previous, recorded, desired, force=force)
+        if reason is None or reason is _UNCHANGED:
+            removable.append(name)
+        else:
+            blocked.append({"name": name, "path": str(destination), "reason": reason})
+    return removable, blocked
+
+
+def installed_skill_problem(target: Path, names: Iterable[str]) -> str | None:
+    for name in names:
+        if _SKILL_NAME.fullmatch(name) is None:
+            return f"{name!r} is not a safe packaged skill name"
+        destination = target / name / "SKILL.md"
+        if problem := _destination_problem(target, destination):
+            return problem
+        try:
+            installed, _ = _read_regular(destination)
+            packaged, _ = _read_regular(SKILL_FILES_DIR / name / "SKILL.md")
+        except OSError as error:
+            return f"{destination} could not be read: {error}"
+        if installed != packaged:
+            return f"{destination} does not match this cv installation"
+    return None
+
+
+def read_receipt(target: Path) -> dict[str, dict[str, str]]:
+    path = target / RECEIPT_NAME
+    try:
+        contents, _node = _read_regular(path)
+    except FileNotFoundError:
+        return {}
+    except OSError as error:
+        _raise_bad_receipt(path, f"it is not a readable regular file ({error})")
+    try:
+        recorded = json.loads(contents)
+    except ValueError as error:
+        _raise_bad_receipt(path, f"it is not readable as a receipt ({error})")
+    entries: dict[str, dict[str, str]] = {}
+    for entry in _receipt_files(path, recorded):
+        relative = entry["path"]
+        if relative in entries:
+            _raise_bad_receipt(path, f"it names {relative} more than once")
+        entries[relative] = entry
+    return entries
+
+
+_UNCHANGED = "unchanged"
+
+
+def _reason_to_skip(
+    previous: bytes | None,
+    recorded: dict[str, str] | None,
+    desired: str,
+    *,
+    force: bool,
+) -> str | None:
+    if previous is None:
+        return None
+    if recorded is None:
+        return "a file cv did not write is already there; move or delete it, then run again"
+    current = _digest(previous)
+    if current == recorded.get("sha256") == desired:
+        return _UNCHANGED
+    if current != recorded.get("sha256") and not force:
+        return "you changed this file after cv wrote it, so `--force` is needed to replace it"
+    return None
+
+
+def _cli_version() -> str:
+    from convergent_cli.main import cli_version
+
+    return cli_version()
+
+
+def _frontmatter(text: str) -> dict[str, str]:
+    if not text.startswith("---\n"):
+        return {}
+    block = text[4:].split("\n---\n", 1)[0]
+    fields: dict[str, str] = {}
+    for line in block.splitlines():
+        if ":" in line and not line.startswith((" ", "\t", "#")):
+            key, value = line.split(":", 1)
+            fields[key.strip()] = value.strip()
+    return fields
+
+
+def _digest(contents: str | bytes) -> str:
+    data = contents.encode("utf-8") if isinstance(contents, str) else contents
+    return hashlib.sha256(data).hexdigest()
+
+
+def _read_regular(path: Path) -> tuple[bytes, os.stat_result]:
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+    descriptor = os.open(path, flags)
+    with os.fdopen(descriptor, "rb") as handle:
+        node = os.fstat(handle.fileno())
+        if not stat.S_ISREG(node.st_mode):
+            raise OSError(f"{path} is not a regular file")
+        return handle.read(), node
+
+
+def _receipt_files(path: Path, recorded: object) -> list[dict[str, str]]:
+    if not isinstance(recorded, dict):
+        _raise_bad_receipt(path, "it is not a json object")
+    version = recorded.get("schema_version")
+    if version != _RECEIPT_SCHEMA_VERSION:
+        newer = isinstance(version, int) and version > _RECEIPT_SCHEMA_VERSION
+        _raise_bad_receipt(
+            path,
+            f"its schema version is {version!r}, not {_RECEIPT_SCHEMA_VERSION}",
+            fix="Upgrade cv, then run the command again." if newer else None,
+        )
+    if recorded.get("object") != _RECEIPT_OBJECT:
+        _raise_bad_receipt(path, f"its object is not {_RECEIPT_OBJECT!r}")
+    files = recorded.get("files")
+    if not isinstance(files, list) or not all(isinstance(entry, dict) for entry in files):
+        _raise_bad_receipt(path, "its files are not a list of json objects")
+    packaged = {skill.name for skill in catalog()} | RETIRED_SKILLS
+    validated: list[dict[str, str]] = []
+    for raw in files:
+        if not all(isinstance(key, str) and isinstance(value, str) for key, value in raw.items()):
+            _raise_bad_receipt(path, "one of its entries contains a non-string field")
+        entry = cast(dict[str, str], raw)
+        name = entry.get("name", "")
+        relative = entry.get("path", "")
+        if _SKILL_NAME.fullmatch(name) is None:
+            _raise_bad_receipt(path, f"its entry has an unsafe skill name {name!r}")
+        if name not in packaged:
+            _raise_bad_receipt(path, f"its entry names unpackaged skill {name!r}")
+        if relative != f"{name}/SKILL.md":
+            _raise_bad_receipt(path, f"its entry path {relative!r} does not match {name!r}")
+        if not entry.get("version"):
+            _raise_bad_receipt(path, f"its entry {relative} has no version")
+        if _SHA256.fullmatch(entry.get("sha256", "")) is None:
+            _raise_bad_receipt(path, f"its entry {relative} has no valid sha256")
+        validated.append(entry)
+    return validated
+
+
+def _raise_bad_receipt(path: Path, problem: str, fix: str | None = None) -> NoReturn:
+    raise SkillError(
+        f"{path} is not a receipt cv can use, because {problem}.",
+        fix=fix or f"Delete {path}, then run the command again.",
+    )
+
+
+def _write_receipt(target: Path, files: dict[str, dict[str, str]]) -> None:
+    receipt = {
+        "object": _RECEIPT_OBJECT,
+        "schema_version": _RECEIPT_SCHEMA_VERSION,
+        "files": [files[path] for path in sorted(files)],
+    }
+    contents = (json.dumps(receipt, indent=2) + "\n").encode()
+    _atomic_write(target / RECEIPT_NAME, contents, mode=0o600)
+
+
+def _atomic_write(path: Path, contents: bytes, *, mode: int) -> tuple[int, int]:
+    temporary = path.with_name(f".{path.name}.{secrets.token_hex(8)}.tmp")
+    descriptor = os.open(
+        temporary,
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
+        mode,
+    )
+    identity: tuple[int, int] | None = None
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(contents)
+            handle.flush()
+            os.fsync(handle.fileno())
+            node = os.fstat(handle.fileno())
+            identity = node.st_dev, node.st_ino
+        os.replace(temporary, path)
+        return identity
+    except BaseException:
+        temporary.unlink(missing_ok=True)
+        if identity is not None:
+            try:
+                current, current_node = _read_regular(path)
+            except OSError:
+                current = None
+            else:
+                if (current_node.st_dev, current_node.st_ino) == identity and current == contents:
+                    return identity
+        raise
+
+
+def _atomic_create(path: Path, contents: bytes, *, mode: int) -> None:
+    temporary = path.with_name(f".{path.name}.{secrets.token_hex(8)}.tmp")
+    descriptor = os.open(
+        temporary,
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
+        mode,
+    )
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(contents)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.link(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def _restore_replaced(
+    replaced: list[tuple[Path, bytes | None, int | None, str, tuple[int, int]]],
+) -> list[str]:
+    failures: list[str] = []
+    for path, previous, mode, written_digest, written_identity in reversed(replaced):
+        try:
+            current, node = _read_regular(path)
+            same_write = (node.st_dev, node.st_ino) == written_identity
+            if not same_write or _digest(current) != written_digest:
+                failures.append(f"{path}: changed after cv wrote it, so it was left in place")
+                continue
+            if previous is None:
+                path.unlink(missing_ok=True)
+            else:
+                _atomic_write(path, previous, mode=mode if mode is not None else 0o644)
+        except OSError as error:
+            failures.append(f"{path}: {error}")
+    return failures
+
+
+def _restore_unlinked(unlinked: list[tuple[Path, bytes, int]]) -> list[str]:
+    failures: list[str] = []
+    for path, previous, mode in reversed(unlinked):
+        try:
+            _make_directories(path.parent)
+            _atomic_create(path, previous, mode=mode)
+        except FileExistsError:
+            failures.append(f"{path}: created after cv removed it, so it was left in place")
+        except OSError as error:
+            failures.append(f"{path}: {error}")
+    return failures
+
+
+def _make_directories(path: Path) -> None:
+    missing: list[Path] = []
+    current = path
+    while current != current.parent:
+        try:
+            node = os.lstat(current)
+        except FileNotFoundError:
+            missing.append(current)
+            current = current.parent
+            continue
+        break
+    else:
+        node = os.lstat(current)
+    if not stat.S_ISDIR(node.st_mode):
+        raise NotADirectoryError(f"{current} is not a directory")
+    for directory in reversed(missing):
+        os.mkdir(directory, 0o755)
+
+
+def _destination_problem(target: Path, destination: Path) -> str | None:
+    current = target
+    relative = destination.relative_to(target)
+    for index, part in enumerate(relative.parts):
+        current /= part
+        try:
+            node = os.lstat(current)
+        except FileNotFoundError:
+            continue
+        if stat.S_ISLNK(node.st_mode):
+            return f"{current} is a symlink"
+        final = index == len(relative.parts) - 1
+        if final and not stat.S_ISREG(node.st_mode):
+            return f"{current} is not a regular file"
+        if not final and not stat.S_ISDIR(node.st_mode):
+            return f"{current} is not a directory"
+    return None
+
+
+__all__ = [
+    "AGENTS_SKILLS",
+    "CLAUDE_SKILLS",
+    "RECEIPT_NAME",
+    "RETIRED_SKILLS",
+    "InstallReport",
+    "PackagedSkill",
+    "SkillError",
+    "catalog",
+    "install",
+    "installed_skill_problem",
+    "read_receipt",
+    "retirements",
+]