resolvescript 0.1.2__py3-none-any.whl

resolve_script/fetch.py

@@ -0,0 +1,90 @@
+"""HTTP(S) download + SHA-256 integrity verification (stdlib only)."""
+
+from __future__ import annotations
+
+import hashlib
+import socket
+import tempfile
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class FetchError(RuntimeError):
+    pass
+
+
+@dataclass
+class Fetched:
+    path: Path
+    sha256: str
+    size: int
+    url: str
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def allow_remote() -> bool:
+    """Whether remote downloads are allowed (default on; off via env)."""
+    import os
+
+    return os.environ.get("RESOLVESCRIPT_ALLOW_NETWORK", "1").lower() not in (
+        "0",
+        "false",
+        "no",
+    )
+
+
+def fetch(
+    url: str,
+    *,
+    dest: Path,
+    expected_sha256: str | None = None,
+    timeout: float = 45.0,
+) -> Fetched:
+    """Download ``url`` to a fresh ``dest``; verify integrity when provided.
+
+    Raises :class:`FetchError` on HTTP errors, or if the downloaded bytes do
+    not match ``expected_sha256`` (the file is then removed).
+    """
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if dest.exists():
+        dest.unlink()
+    if not allow_remote():
+        raise FetchError("network downloads are disabled (RESOLVESCRIPT_ALLOW_NETWORK=0)")
+    previous = socket.getdefaulttimeout()
+    socket.setdefaulttimeout(timeout)
+    try:
+        try:
+            with urllib.request.urlopen(url, timeout=timeout) as response:
+                data = response.read()
+        except Exception as exc:  # URLError, HTTPError, timeout…
+            raise FetchError(f"failed to download {url}: {exc}") from exc
+    finally:
+        socket.setdefaulttimeout(previous)
+    size = len(data)
+    digest = hashlib.sha256(data).hexdigest()
+    if expected_sha256 and digest != expected_sha256:
+        raise FetchError(
+            f"integrity check failed for {url}: expected sha256 "
+            f"{expected_sha256}, got {digest}"
+        )
+    dest.write_bytes(data)
+    return Fetched(path=dest, sha256=digest, size=size, url=url)
+
+
+def fetch_json(
+    url: str, *, timeout: float = 45.0
+) -> object:
+    """Download a JSON document (used for the GitHub tags API in tests)."""
+    with tempfile.TemporaryDirectory() as tmp:
+        result = fetch(url, dest=Path(tmp) / "payload", timeout=timeout)
+    import json
+
+    return json.loads(result.path.read_text("utf-8"))

resolve_script/install/__init__.py

@@ -0,0 +1,49 @@
+"""Installer core: per-OS script roots, atomic install, registry, uninstall."""
+
+from .discovery import default_scripts_root, resolve_scripts_root, target_dir
+from .installer import (
+    InstalledFile,
+    InstallError,
+    InstallOptions,
+    InstallResult,
+    discover_entrypoint,
+    install_package,
+    install_project,
+    select_files,
+    uninstall_package,
+)
+from .registry import (
+    REGISTRY_REL,
+    SCHEMA_VERSION,
+    RegistryError,
+    add_or_update_entry,
+    get_extension,
+    read_registry,
+    registry_path,
+    remove_entry,
+    write_registry,
+)
+
+__all__ = [
+    "REGISTRY_REL",
+    "SCHEMA_VERSION",
+    "InstallError",
+    "InstallOptions",
+    "InstallResult",
+    "InstalledFile",
+    "RegistryError",
+    "add_or_update_entry",
+    "default_scripts_root",
+    "discover_entrypoint",
+    "get_extension",
+    "install_package",
+    "install_project",
+    "read_registry",
+    "registry_path",
+    "remove_entry",
+    "resolve_scripts_root",
+    "select_files",
+    "target_dir",
+    "uninstall_package",
+    "write_registry",
+]

resolve_script/install/discovery.py

@@ -0,0 +1,57 @@
+"""Per-OS DaVinci Resolve Scripts-root discovery.
+
+The Scripts root is the parent of the well-known target folders
+(``Comp``, ``Utility``, ``Tool``, …) that appear in Resolve's Workspace menus.
+The standard layout is ``…/Fusion/Scripts`` on every OS.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+from pathlib import Path
+
+from ..config import ENV_SCRIPTS_ROOT
+from ..manifest.model import TARGET_SUGGESTIONS, ManifestError, Target
+
+
+def default_scripts_root() -> Path:
+    """Return the OS-default DaVinci Resolve Scripts root (no override)."""
+    system = platform.system()
+    home = Path.home()
+    if system == "Windows":
+        appdata = os.environ.get("APPDATA") or str(home)
+        return Path(appdata) / "Blackmagic Design" / "DaVinci Resolve" / "Fusion" / "Scripts"
+    if system == "Darwin":
+        return (
+            home
+            / "Library"
+            / "Application Support"
+            / "Blackmagic Design"
+            / "DaVinci Resolve"
+            / "Fusion"
+            / "Scripts"
+        )
+    # Linux and anything else
+    return home / ".local" / "share" / "DaVinci Resolve" / "Fusion" / "Scripts"
+
+
+def resolve_scripts_root(override: str | Path | None = None) -> Path:
+    """Effective Scripts root: explicit override, then env var, then OS default."""
+    if override:
+        return Path(override).expanduser()
+    env_value = os.environ.get(ENV_SCRIPTS_ROOT, "")
+    if env_value.strip():
+        return Path(env_value).expanduser()
+    return default_scripts_root()
+
+
+def target_dir(scripts_root: Path, target: str) -> Path:
+    """Validate a target name and return its folder under the Scripts root."""
+    if target == Target.ROOT.value:
+        return Path(scripts_root)
+    if target not in Target.valid_names():
+        suggestion = TARGET_SUGGESTIONS.get(target.lower())
+        hint = f" (did you mean '{suggestion}'?)" if suggestion else ""
+        raise ManifestError(f"unknown script target '{target}'{hint}")
+    return Path(scripts_root) / target

resolve_script/install/installer.py

@@ -0,0 +1,397 @@
+"""Atomic install of a Resolve script / extension into a Scripts root.
+
+Design:
+
+- Files are selected from the package tree via ``install.include`` /
+  ``install.exclude`` patterns (default: everything except caches).
+- A staging directory is built inside the destination's parent (same volume),
+  the staged entry file is ``py_compile``-checked, and only then the tree is
+  renamed into place. Any failure discards the stage — no partial installs.
+- The registry is consulted before writing: if another extension already owns
+  a destination file, the install is refused unless ``force`` is set.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import py_compile
+import re
+import shutil
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..manifest.model import Manifest, ManifestError
+from .registry import add_or_update_entry, get_extension, installed_at_now, read_registry
+
+
+class InstallError(Exception):
+    pass
+
+
+@dataclass
+class InstallOptions:
+    """Tunables for an install run."""
+
+    scripts_root: Path
+    targets: tuple[str, ...] = ()
+    force: bool = False
+    dry_run: bool = False
+    source: str = "local"
+    resolved: str = ""
+    integrity: str = ""  # sha256 of the downloaded artifact (source verify)
+
+    def __post_init__(self) -> None:
+        self.scripts_root = Path(self.scripts_root)
+
+
+@dataclass
+class InstalledFile:
+    rel: str  # path of the file relative to the extension's install container
+    sha256: str
+    size: int
+
+
+@dataclass
+class InstallResult:
+    key: str
+    name: str
+    version: str
+    targets: tuple[str, ...]
+    files: list[InstalledFile]
+    installed_at: str
+    dry_run: bool = False
+    container: Path | None = None
+
+    def describe(self) -> list[str]:
+        lines = [
+            f"Installed {self.name} {self.version} -> {self.container}"
+            if self.container
+            else f"Would install {self.name} {self.version}",
+            f"  targets: {', '.join(self.targets)}",
+        ]
+        for file in self.files:
+            lines.append(f"  {file.rel}  ({file.size} bytes)")
+        return lines
+
+
+def _glob_regex(pattern: str) -> re.Pattern[str]:
+    """Convert a ``**``-aware glob pattern to a full-path regex."""
+    if not pattern:
+        return re.compile(r"$^")
+    if pattern == "**":
+        return re.compile(r"^.+$")
+    if pattern.endswith("/**"):
+        prefix = pattern[:-3]
+        inner = _glob_regex(prefix).pattern
+        # strip the ^ and $ anchors from inner and append the recursive tail
+        core = inner[1:-1] if inner.startswith("^") and inner.endswith("$") else inner
+        return re.compile(f"^{core}(?:/.*)?$")
+    parts = pattern.split("/")
+    rx: list[str] = []
+    for part in parts:
+        if part == "**":
+            rx.append("(?:[^/]+/)*")
+        else:
+            rx.append(part.replace("*", "[^/]*").replace("?", "[^/]"))
+    return re.compile("^" + "".join(rx) + "$")
+
+
+def _matches_any(patterns: list[str], rel: str) -> bool:
+    return any(_glob_regex(p).match(rel) for p in patterns)
+
+
+def select_files(package_dir: Path, include: list[str] | None = None, exclude: list[str] | None = None) -> list[Path]:
+    """Return install files (relative to ``package_dir``) selected by include/exclude."""
+    include = include or []
+    exclude = exclude or []
+    result: list[Path] = []
+    for file in sorted(package_dir.rglob("*")):
+        if not file.is_file():
+            continue
+        rel = file.relative_to(package_dir)
+        if any(part in ("__pycache__", ".git", ".resolvescript") for part in rel.parts):
+            continue
+        rel_str = rel.as_posix()
+        if include and not _matches_any(include, rel_str):
+            continue
+        if exclude and _matches_any(exclude, rel_str):
+            continue
+        result.append(rel)
+    return result
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def discover_entrypoint(package_dir: Path, manifest: Manifest) -> Path | None:
+    """Locate the runnable entry file, if any.
+
+    Priority: ``manifest.entrypoint``, a root ``<name>.py`` script, or the
+    consolidated ``dist/<consolidate.output>`` build.
+    """
+    if manifest.entrypoint:
+        candidate = package_dir / manifest.entrypoint
+        if not candidate.is_file():
+            raise InstallError(f"manifest entrypoint not found: {candidate}")
+        return candidate
+    direct = package_dir / f"{manifest.name}.py"
+    if direct.is_file():
+        return direct
+    if manifest.consolidate.output:
+        candidate = package_dir / "dist" / manifest.consolidate.output
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _compile_entry(staged_entry: Path) -> None:
+    """Syntax-check the staged entry file; raises InstallError on failure.
+
+    The bytecode is written outside the staging tree so it never ships.
+    """
+    try:
+        with tempfile.TemporaryDirectory(prefix="resolvescript-pycheck-") as tmp:
+            py_compile.compile(
+                str(staged_entry),
+                cfile=str(Path(tmp) / "check.pyc"),
+                doraise=True,
+            )
+    except py_compile.PyCompileError as exc:
+        raise InstallError(f"entry file is not valid Python: {exc}") from exc
+
+
+def _occupied_map(registry: dict[str, Any], scripts_root: Path):
+    """Map ``(target, relative-path)`` → owning extension name."""
+
+    occupied: dict[tuple[str, str], str] = {}
+    for ext_name, entry in registry.get("extensions", {}).items():
+        owner = entry.get("name") or ext_name
+        for target in entry.get("targets", []):
+            for rel in entry.get("files", []):
+                occupied[(target, str(rel))] = owner
+    return occupied
+
+
+def install_package(
+    package_dir: Path | str,
+    manifest: Manifest,
+    options: InstallOptions,
+) -> InstallResult:
+    """Install a materialized package dir (manifest + files) into a Scripts root."""
+    from .discovery import target_dir
+
+    package_dir = Path(package_dir).resolve()
+    scripts_root = Path(options.scripts_root).resolve()
+    targets = tuple(options.targets) or tuple(manifest.targets) or ("Comp",)
+    as_directory = manifest.install.as_directory
+
+    rel_files = select_files(package_dir, manifest.install.include, manifest.install.exclude)
+    entrypoint = discover_entrypoint(package_dir, manifest)
+    entry_rel = entrypoint.relative_to(package_dir).as_posix() if entrypoint is not None else None
+    if entry_rel is not None and not any(r.as_posix() == entry_rel for r in rel_files):
+        rel_files.append(Path(entry_rel))
+
+    if not as_directory and entry_rel is None:
+        raise InstallError(
+            f"cannot install {manifest.name} as a single file: no entrypoint "
+            "(set manifest 'entrypoint' or provide a <name>.py)"
+        )
+
+    # containers[target] = folder that will hold the installed files
+    containers: dict[str, Path] = {}
+    for target in targets:
+        base = target_dir(scripts_root, target)
+        containers[target] = base / manifest.name if as_directory else base
+
+    # dest layout: for directory installs preserve relative structure; for
+    # single-file installs install just the entrypoint under its basename
+    layout: dict[str, str] = {r.as_posix(): r.as_posix() for r in rel_files}
+    if not as_directory:
+        assert entry_rel is not None
+        layout = {entry_rel: Path(entry_rel).name}
+
+    dest_entries: list[tuple[Path, Path, str]] = []  # (source, dest, target)
+    for target in targets:
+        container = containers[target]
+        target_base_rel = target_dir(scripts_root, target)
+        for rel, dest_rel in layout.items():
+            src = package_dir / rel
+            dest = container / dest_rel
+            dest_entries.append((src, dest, target))
+            assert dest.is_relative_to(target_base_rel), (dest, target_base_rel)
+
+    registry = read_registry(scripts_root)
+    occupied = _occupied_map(registry, scripts_root)
+    if not options.force:
+        for _src, dest, target in dest_entries:
+            rel = dest.relative_to(target_dir(scripts_root, target)).as_posix()
+            owner = occupied.get((target, rel))
+            if owner is not None and owner != manifest.name:
+                raise InstallError(
+                    f"install would overwrite '{rel}' in '{target}' which is owned by "
+                    f"'{owner}' (use --force to overwrite)"
+                )
+
+    if options.dry_run:
+        seen: set[tuple[str, str]] = set()
+        files: list[InstalledFile] = []
+        for src, dest, target in dest_entries:
+            rel = dest.relative_to(target_dir(scripts_root, target)).as_posix()
+            if (target, rel) in seen:
+                continue
+            seen.add((target, rel))
+            files.append(InstalledFile(rel, sha256="", size=src.stat().st_size))
+        return InstallResult(
+            key=manifest.id or manifest.name,
+            name=manifest.name,
+            version=manifest.version,
+            targets=targets,
+            files=files,
+            installed_at=installed_at_now(),
+            dry_run=True,
+            container=containers[targets[0]],
+        )
+
+    installed_files: list[InstalledFile] = []
+    for target in targets:
+        container = containers[target]
+        container.parent.mkdir(parents=True, exist_ok=True)
+        stage = Path(
+            tempfile.mkdtemp(prefix=".resolvescript-stage-", dir=str(container.parent))
+        )
+        try:
+            for src, dest, entry_target in dest_entries:
+                if entry_target != target:
+                    continue
+                staged = stage / dest.relative_to(container)
+                staged.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(src, staged)
+                installed_files.append(
+                    InstalledFile(
+                        rel=dest.relative_to(container).as_posix(),
+                        sha256=_sha256(src),
+                        size=src.stat().st_size,
+                    )
+                )
+            if entry_rel is not None:
+                staged_entry = stage / (
+                    Path(entry_rel).name if not as_directory else Path(entry_rel)
+                )
+                _compile_entry(staged_entry)
+
+            if container.exists():
+                shutil.rmtree(container)
+            stage.replace(container)
+        except InstallError:
+            shutil.rmtree(stage, ignore_errors=True)
+            raise
+        except OSError as exc:
+            shutil.rmtree(stage, ignore_errors=True)
+            raise InstallError(f"failed to install into {container}: {exc}") from exc
+
+    entry_sha = _sha256(entrypoint) if entrypoint is not None else ""
+    result = InstallResult(
+        key=manifest.id or manifest.name,
+        name=manifest.name,
+        version=manifest.version,
+        targets=targets,
+        files=installed_files,
+        installed_at=installed_at_now(),
+        container=containers[targets[0]],
+    )
+    entry = {
+        "id": manifest.id or manifest.name,
+        "name": manifest.name,
+        "version": manifest.version,
+        "kind": manifest.kind,
+        "as_directory": as_directory,
+        "source": options.source
+        if options.source != "local"
+        else (manifest.release.github_spec or manifest.release.url or "local"),
+        "resolved": options.resolved,
+        "integrity": options.integrity or entry_sha,
+        "files": sorted(
+            {f"{manifest.name}/{f.rel}" if as_directory else f.rel for f in installed_files}
+        ),
+        "targets": list(targets),
+        "compat": manifest.compat.as_dict(),
+        "installed_at": result.installed_at,
+    }
+    if manifest.release.owner or manifest.release.repo or manifest.release.url:
+        entry["release"] = manifest.release.as_dict()
+    add_or_update_entry(scripts_root, result.key, entry)
+    return result
+
+
+def install_project(
+    root: Path | str,
+    options: InstallOptions,
+    manifest: Manifest | None = None,
+) -> InstallResult:
+    """Author flow: install the project in ``root`` (``resolvescript install``)."""
+    root = Path(root).resolve()
+    if manifest is None:
+        from ..manifest.json_reader import load_manifest
+
+        manifest_path = root / "manifest.json"
+        if not manifest_path.is_file():
+            from ..manifest.xml_reader import load_manifest as load_xml
+
+            manifest_path = root / "manifest.xml"
+            if not manifest_path.is_file():
+                raise ManifestError(
+                    f"no manifest.json or manifest.xml in {root} (run 'resolvescript create')"
+                )
+            manifest = load_xml(manifest_path)
+        else:
+            manifest = load_manifest(manifest_path)
+    return install_package(root, manifest, options)
+
+
+def uninstall_package(name: str, options: InstallOptions) -> list[str]:
+    """Remove an extension's installed files via the registry; returns removed paths."""
+    from .discovery import target_dir
+
+    scripts_root = Path(options.scripts_root).resolve()
+    registry = read_registry(scripts_root)
+    entry = get_extension(registry, name)
+    if entry is None:
+        raise InstallError(f"'{name}' is not installed in {scripts_root}")
+
+    removed: list[str] = []
+    as_directory = bool(entry.get("as_directory", True))
+    key = entry.get("id") or name
+    for target in entry.get("targets", []):
+        base = target_dir(scripts_root, target)
+        if as_directory:
+            container = base / (entry.get("name") or key)
+            if container.is_dir():
+                shutil.rmtree(container)
+                removed.append(str(container))
+        else:
+            for rel in entry.get("files", []):
+                path = base / str(rel)
+                if path.is_file() or path.is_symlink() and not path.exists():
+                    path.unlink()
+                    removed.append(str(path))
+        # clean up now-empty directories up to the Scripts root
+        current = container.parent if as_directory else base
+        while current != scripts_root and current.is_dir() and not any(current.iterdir()):
+            current.rmdir()
+            current = current.parent
+
+    remove_entry_from_registry(scripts_root, key)
+    return removed or [f"registry entry '{name}'"]
+
+
+def remove_entry_from_registry(scripts_root: Path, key: str) -> None:
+    from .registry import remove_entry
+
+    remove_entry(scripts_root, key) or remove_entry(scripts_root, key.split(":")[-1])

resolve_script/install/registry.py

@@ -0,0 +1,106 @@
+"""Install registry: ``Scripts/.resolvescript/install.json``.
+
+Records every installed extension so ``manage list``, ``remove`` and conflict
+detection know exactly which files belong to whom. Written atomically.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+REGISTRY_REL = Path(".resolvescript") / "install.json"
+SCHEMA_VERSION = 1
+
+EMPTY_REGISTRY: dict[str, Any] = {"schema_version": SCHEMA_VERSION, "extensions": {}}
+
+
+class RegistryError(Exception):
+    pass
+
+
+def registry_path(scripts_root: Path | str) -> Path:
+    return Path(scripts_root) / REGISTRY_REL
+
+
+def read_registry(scripts_root: Path | str) -> dict[str, Any]:
+    """Load the registry; a missing or empty file yields an empty registry."""
+    path = registry_path(scripts_root)
+    if not path.is_file():
+        return copy.deepcopy(EMPTY_REGISTRY)
+    try:
+        raw: Any = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise RegistryError(f"registry is corrupt at {path}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise RegistryError(f"registry at {path} is not a JSON object")
+    raw.setdefault("schema_version", SCHEMA_VERSION)
+    raw.setdefault("extensions", {})
+    if not isinstance(raw["extensions"], dict):
+        raise RegistryError(f"registry at {path} has a non-object 'extensions'")
+    return raw
+
+
+def write_registry(scripts_root: Path | str, registry: dict[str, Any]) -> None:
+    """Persist the registry atomically (temp file + rename)."""
+    root = Path(scripts_root)
+    path = registry_path(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(registry, indent=2, sort_keys=True) + "\n"
+    fd, tmp = tempfile.mkstemp(prefix=".install-", suffix=".json", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(payload)
+        Path(tmp).replace(path)
+    except Exception:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def get_extension(registry: dict[str, Any], key: str) -> dict[str, Any] | None:
+    extensions = registry.get("extensions", {})
+    for ext_key, entry in extensions.items():
+        if ext_key == key or entry.get("id") == key or entry.get("name") == key:
+            return entry
+    return None
+
+
+def extension_key(registry: dict[str, Any], name: str, manifest_id: str | None) -> str:
+    existing = get_extension(registry, name)
+    if existing is not None and manifest_id and existing.get("id") != manifest_id:
+        return name
+    return manifest_id or name
+
+
+def add_or_update_entry(
+    scripts_root: Path | str,
+    key: str,
+    entry: dict[str, Any],
+) -> dict[str, Any]:
+    registry = read_registry(scripts_root)
+    registry["extensions"][key] = entry
+    write_registry(scripts_root, registry)
+    return registry
+
+
+def remove_entry(scripts_root: Path | str, key: str) -> dict[str, Any] | None:
+    """Delete an extension from the registry; returns the removed entry."""
+    registry = read_registry(scripts_root)
+    entry = registry["extensions"].pop(key, None)
+    if entry is None:
+        for ext_key, candidate in list(registry["extensions"].items()):
+            if candidate.get("id") == key or candidate.get("name") == key:
+                entry = registry["extensions"].pop(ext_key)
+                break
+    if entry is not None:
+        write_registry(scripts_root, registry)
+    return entry
+
+
+def installed_at_now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")