stemmata 0.0.1__py3-none-any.whl

stemmata/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import version as _pkg_version, PackageNotFoundError
+
+try:
+    __version__ = _pkg_version("stemmata")
+except PackageNotFoundError:
+    __version__ = "0.0.1"

stemmata/__main__.py

@@ -0,0 +1,3 @@
+from stemmata.cli import main
+
+raise SystemExit(main())

stemmata/bundle.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import gzip
+import hashlib
+import io
+import os
+import tarfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from stemmata.errors import SchemaError
+
+
+# Deterministic build constants. All members carry the same mtime so two
+# builds of identical inputs produce byte-identical tarballs.
+_DETERMINISTIC_MTIME = 0
+_FILE_MODE = 0o644
+_DIR_MODE = 0o755
+_BOM_BYTES = b"\xef\xbb\xbf"
+
+
+@dataclass
+class BundleMember:
+    arcname: str
+    data: bytes
+    is_dir: bool = False
+
+
+def _normalise_yaml_bytes(raw: bytes, *, file: str) -> bytes:
+    """Strip BOM and normalise CRLF -> LF for YAML payloads on publish."""
+    if raw.startswith(_BOM_BYTES):
+        raw = raw[len(_BOM_BYTES):]
+    if b"\r\n" in raw or b"\r" in raw:
+        raw = raw.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+    return raw
+
+
+def _is_safe_arcname(arcname: str) -> bool:
+    if not arcname:
+        return False
+    if arcname.startswith("/") or "\\" in arcname:
+        return False
+    parts = arcname.split("/")
+    for p in parts:
+        if p in ("", ".", ".."):
+            return False
+    return True
+
+
+def collect_members(
+    package_root: Path,
+    extra_files: list[str],
+    yaml_paths: list[str],
+) -> list[BundleMember]:
+    """Collect tarball members from a publish source directory.
+
+    ``yaml_paths`` are POSIX-relative paths to YAML payload files (subject to
+    BOM/CRLF normalisation). ``extra_files`` are additional package-relative
+    files to ship verbatim (e.g. ``package.json``, ``README.md``, ``LICENSE``).
+    """
+    members: list[BundleMember] = []
+    seen: set[str] = set()
+
+    def _add_file(rel: str, data: bytes) -> None:
+        if rel in seen:
+            return
+        seen.add(rel)
+        if not _is_safe_arcname(rel):
+            raise SchemaError(
+                f"unsafe path in bundle: {rel!r}",
+                file=str(package_root / rel),
+                field_name="bundle",
+                reason="unsafe_path",
+            )
+        members.append(BundleMember(arcname=rel, data=data))
+
+    for rel in extra_files:
+        if not _is_safe_arcname(rel):
+            raise SchemaError(
+                f"unsafe path in bundle: {rel!r}",
+                file=str(package_root / rel),
+                field_name="bundle",
+                reason="unsafe_path",
+            )
+        full = package_root / rel
+        if not full.is_file():
+            continue
+        if full.is_symlink():
+            raise SchemaError(
+                f"refusing to bundle symlink: {rel!r}",
+                file=str(full),
+                field_name="bundle",
+                reason="symlink_forbidden",
+            )
+        _add_file(rel, full.read_bytes())
+
+    for rel in yaml_paths:
+        full = package_root / rel
+        if not full.is_file():
+            raise SchemaError(
+                f"prompt payload file declared by manifest does not exist: {rel}",
+                file=str(full),
+                field_name="path",
+                reason="missing_prompt_file",
+            )
+        if full.is_symlink():
+            raise SchemaError(
+                f"refusing to bundle symlink: {rel!r}",
+                file=str(full),
+                field_name="bundle",
+                reason="symlink_forbidden",
+            )
+        raw = full.read_bytes()
+        normalised = _normalise_yaml_bytes(raw, file=str(full))
+        _add_file(rel, normalised)
+
+    members.sort(key=lambda m: m.arcname)
+    return members
+
+
+def build_tarball(members: list[BundleMember]) -> bytes:
+    """Build a deterministic gzipped tarball with a single ``package/`` root.
+
+    All members share mtime 0, uid/gid 0, owner ""/"" and mode 0644 (files) or
+    0755 (dirs). Entries are emitted in sorted arcname order. Gzip is wrapped
+    around the tar stream with a fixed header (no embedded filename / mtime).
+    """
+    tar_buf = io.BytesIO()
+    with tarfile.open(fileobj=tar_buf, mode="w", format=tarfile.USTAR_FORMAT) as tf:
+        emitted_dirs: set[str] = set()
+
+        def _ensure_dir(dirpath: str) -> None:
+            if not dirpath or dirpath in emitted_dirs:
+                return
+            parent = "/".join(dirpath.split("/")[:-1])
+            if parent:
+                _ensure_dir(parent)
+            info = tarfile.TarInfo(name=f"package/{dirpath}/")
+            info.type = tarfile.DIRTYPE
+            info.mode = _DIR_MODE
+            info.mtime = _DETERMINISTIC_MTIME
+            info.uid = 0
+            info.gid = 0
+            info.uname = ""
+            info.gname = ""
+            tf.addfile(info)
+            emitted_dirs.add(dirpath)
+
+        # Always emit the root package directory itself as the first entry.
+        root_info = tarfile.TarInfo(name="package/")
+        root_info.type = tarfile.DIRTYPE
+        root_info.mode = _DIR_MODE
+        root_info.mtime = _DETERMINISTIC_MTIME
+        root_info.uid = 0
+        root_info.gid = 0
+        root_info.uname = ""
+        root_info.gname = ""
+        tf.addfile(root_info)
+
+        for m in members:
+            if m.is_dir:
+                _ensure_dir(m.arcname)
+                continue
+            parent = "/".join(m.arcname.split("/")[:-1])
+            if parent:
+                _ensure_dir(parent)
+            info = tarfile.TarInfo(name=f"package/{m.arcname}")
+            info.size = len(m.data)
+            info.mode = _FILE_MODE
+            info.mtime = _DETERMINISTIC_MTIME
+            info.uid = 0
+            info.gid = 0
+            info.uname = ""
+            info.gname = ""
+            info.type = tarfile.REGTYPE
+            tf.addfile(info, io.BytesIO(m.data))
+
+    tar_bytes = tar_buf.getvalue()
+    gz_buf = io.BytesIO()
+    # mtime=0 + filename=None + no comment -> reproducible gzip header.
+    with gzip.GzipFile(filename="", mode="wb", fileobj=gz_buf, mtime=0) as gz:
+        gz.write(tar_bytes)
+    return gz_buf.getvalue()
+
+
+def integrity_sha512(data: bytes) -> str:
+    import base64
+    return "sha512-" + base64.b64encode(hashlib.sha512(data).digest()).decode("ascii")
+
+
+def shasum_sha1(data: bytes) -> str:
+    return hashlib.sha1(data).hexdigest()
+
+
+def tarball_filename(name: str, version: str) -> str:
+    if name.startswith("@") and "/" in name:
+        _, simple = name.split("/", 1)
+    else:
+        simple = name
+    return f"{simple}-{version}.tgz"

stemmata/cache.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import os
+import shutil
+import sys
+import tarfile
+import tempfile
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator
+
+from stemmata.errors import CacheError, SchemaError
+
+
+MAX_DECOMPRESSED_BYTES = 256 * 1024 * 1024
+
+
+def default_cache_dir() -> Path:
+    override = os.environ.get("PROMPT_CLI_CACHE_DIR")
+    if override:
+        return Path(override)
+    return Path.home() / ".cache" / "stemmata"
+
+
+@dataclass
+class Cache:
+    root: Path
+
+    def __post_init__(self) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+        (self.root / "packages").mkdir(exist_ok=True)
+        (self.root / "locks").mkdir(exist_ok=True)
+        (self.root / "staging").mkdir(exist_ok=True)
+
+    def package_dir(self, name: str, version: str) -> Path:
+        safe = _safe_dirname(name)
+        return self.root / "packages" / safe / version
+
+    def has_package(self, name: str, version: str) -> bool:
+        return self.package_dir(name, version).is_dir()
+
+    @contextlib.contextmanager
+    def lock(self, name: str, version: str) -> Iterator[None]:
+        safe = _safe_dirname(f"{name}@{version}")
+        lock_path = self.root / "locks" / f"{safe}.lock"
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR)
+        deadline = time.monotonic() + 60.0
+        try:
+            if sys.platform == "win32":
+                import msvcrt
+                if os.fstat(fd).st_size < 1:
+                    os.write(fd, b"\0")
+                while True:
+                    os.lseek(fd, 0, os.SEEK_SET)
+                    try:
+                        msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                        break
+                    except OSError:
+                        if time.monotonic() > deadline:
+                            raise CacheError(str(lock_path), "timed out waiting for lock")
+                        time.sleep(0.05)
+                try:
+                    yield
+                finally:
+                    os.lseek(fd, 0, os.SEEK_SET)
+                    try:
+                        msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+                    except OSError:
+                        pass
+            else:
+                import fcntl
+                while True:
+                    try:
+                        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                        break
+                    except (BlockingIOError, OSError):
+                        if time.monotonic() > deadline:
+                            raise CacheError(str(lock_path), "timed out waiting for lock")
+                        time.sleep(0.05)
+                try:
+                    yield
+                finally:
+                    fcntl.flock(fd, fcntl.LOCK_UN)
+        finally:
+            os.close(fd)
+
+    def install_tarball(self, name: str, version: str, tarball_bytes: bytes, *, max_decompressed: int = MAX_DECOMPRESSED_BYTES, force: bool = False) -> Path:
+        target = self.package_dir(name, version)
+        if target.is_dir() and not force:
+            return target
+        staging = self.root / "staging" / f"{_safe_dirname(name)}-{version}-{uuid.uuid4().hex}"
+        staging.mkdir(parents=True, exist_ok=False)
+        tmp_tar = staging / "archive.tgz"
+        tmp_tar.write_bytes(tarball_bytes)
+        try:
+            _extract_tarball(tmp_tar, staging / "pkg", max_decompressed=max_decompressed)
+        except (SchemaError, CacheError):
+            shutil.rmtree(staging, ignore_errors=True)
+            raise
+        target.parent.mkdir(parents=True, exist_ok=True)
+        evict_staging: Path | None = None
+        if target.exists():
+            evict_staging = self.root / "staging" / f"evict-{uuid.uuid4().hex}"
+            os.replace(target, evict_staging)
+        os.replace(staging / "pkg", target)
+        shutil.rmtree(staging, ignore_errors=True)
+        if evict_staging is not None:
+            shutil.rmtree(evict_staging, ignore_errors=True)
+        return target
+
+    def evict(self, name: str, version: str) -> tuple[bool, int]:
+        target = self.package_dir(name, version)
+        if not target.exists():
+            return False, 0
+        try:
+            with self.lock(name, version):
+                size = _dir_size(target)
+                staging = self.root / "staging" / f"evict-{uuid.uuid4().hex}"
+                os.replace(target, staging)
+                shutil.rmtree(staging, ignore_errors=True)
+                return True, size
+        except CacheError:
+            return False, 0
+
+    def clear_all(self) -> tuple[int, int]:
+        pkgs_root = self.root / "packages"
+        removed = 0
+        bytes_freed = 0
+        if not pkgs_root.exists():
+            return 0, 0
+        for scope_dir in pkgs_root.iterdir():
+            if not scope_dir.is_dir():
+                continue
+            for version_dir in scope_dir.iterdir():
+                if not version_dir.is_dir():
+                    continue
+                name = _unsafe_dirname(scope_dir.name)
+                version = version_dir.name
+                ok, size = self.evict(name, version)
+                if ok:
+                    removed += 1
+                    bytes_freed += size
+            with contextlib.suppress(OSError):
+                if not any(scope_dir.iterdir()):
+                    scope_dir.rmdir()
+        return removed, bytes_freed
+
+
+def _safe_dirname(name: str) -> str:
+    return name.replace("/", "__").replace("@", "AT_")
+
+
+def _unsafe_dirname(name: str) -> str:
+    return name.replace("__", "/").replace("AT_", "@")
+
+
+def _dir_size(path: Path) -> int:
+    total = 0
+    for root, _dirs, files in os.walk(path):
+        for f in files:
+            with contextlib.suppress(OSError):
+                total += os.path.getsize(os.path.join(root, f))
+    return total
+
+
+def _extract_tarball(tar_path: Path, dest: Path, *, max_decompressed: int) -> None:
+    dest.mkdir(parents=True, exist_ok=True)
+    total = 0
+    try:
+        with tarfile.open(tar_path, mode="r:gz") as tf:
+            try:
+                tf.extraction_filter = tarfile.data_filter  # type: ignore[attr-defined]
+            except AttributeError:
+                raise CacheError(str(dest), "python 3.12+ required for safe tar extraction")
+            members: list[tarfile.TarInfo] = []
+            for m in tf.getmembers():
+                name = m.name.replace("\\", "/")
+                if name.startswith("/") or ".." in name.split("/"):
+                    raise SchemaError(
+                        f"tarball contains unsafe path: {m.name!r}",
+                        file=str(tar_path),
+                        field_name="tarball",
+                        reason="path_traversal",
+                    )
+                if m.issym() or m.islnk():
+                    raise SchemaError(
+                        f"tarball contains symlink/hardlink: {m.name!r}",
+                        file=str(tar_path),
+                        field_name="tarball",
+                        reason="symlink_forbidden",
+                    )
+                if m.isdev() or m.isfifo():
+                    raise SchemaError(
+                        f"tarball contains device/FIFO: {m.name!r}",
+                        file=str(tar_path),
+                        field_name="tarball",
+                        reason="device_forbidden",
+                    )
+                if m.isfile():
+                    if m.mode & 0o111:
+                        raise SchemaError(
+                            f"tarball file has executable bit: {m.name!r}",
+                            file=str(tar_path),
+                            field_name="tarball",
+                            reason="exec_bit",
+                        )
+                    total += m.size
+                    if total > max_decompressed:
+                        raise CacheError(str(dest), "decompression size limit exceeded")
+                members.append(m)
+
+            for m in members:
+                name = m.name.replace("\\", "/")
+                if name.startswith("package/"):
+                    relname = name[len("package/"):]
+                else:
+                    relname = name
+                if not relname:
+                    continue
+                target = dest / relname
+                target.parent.mkdir(parents=True, exist_ok=True)
+                if m.isdir():
+                    target.mkdir(exist_ok=True)
+                    continue
+                extracted = tf.extractfile(m)
+                if extracted is None:
+                    continue
+                data = extracted.read()
+                if target.exists():
+                    target.unlink()
+                target.write_bytes(data)
+    except tarfile.TarError as e:
+        raise CacheError(str(tar_path), f"invalid tarball: {e}")