resolvescript 0.1.2__py3-none-any.whl

resolve_script/scaffold.py

@@ -0,0 +1,126 @@
+"""Scaffolder for ``resolvescript create``.
+
+Templates are plain files with ``@KEY@`` placeholders (stdlib substitution, no
+Jinja dependency). Every placeholder-keyed file in the template tree is copied
+into the new project; the ``{{ name }}`` package directory is instantiated to
+the project name.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from pathlib import Path
+
+from . import __version__
+
+TEMPLATES_DIR = Path(__file__).parent / "templates"
+DEFAULT_VERSION = "0.1.0"
+
+_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+class ScaffoldError(Exception):
+    pass
+
+
+def normalize_name(name: str) -> str:
+    """Collapse a requested name into a valid Python package identifier."""
+    slug = re.sub(r"[^A-Za-z0-9_]+", "_", name).strip("_")
+    if not _NAME_RE.match(slug):
+        raise ScaffoldError(f"'{name}' cannot be used as a project/package name (got '{slug}')")
+    return slug
+
+
+def render(text: str, values: dict[str, str]) -> str:
+    """Substitute ``@KEY@`` placeholders, preserving leftover placeholders."""
+
+    def _sub(match: re.Match[str]) -> str:
+        key = match.group(1)
+        return values.get(key, match.group(0))
+
+    return re.sub(r"@([A-Za-z0-9_]+)@", _sub, text)
+
+
+def _walk_templates(root: Path) -> Iterator[Path]:
+    cache_dirs = {"__pycache__"}
+    return (
+        p
+        for p in root.rglob("*")
+        if p.is_file()
+        and p.parent.name not in cache_dirs
+        and p.suffix not in {".pyc", ".pyo", ".pyd"}
+    )
+
+
+def build_values(name: str, **overrides: str) -> dict[str, str]:
+    values = {
+        "NAME": name,
+        "VERSION": DEFAULT_VERSION,
+        "DESCRIPTION": f"{name} — a DaVinci Resolve script built with ResolveScript",
+        "AUTHOR": "",
+        "RESOLVESCRIPT_VERSION": __version__,
+    }
+    for key, value in overrides.items():
+        if value is not None:
+            values[key.upper()] = value
+    return values
+
+
+def scaffold_project(
+    name: str,
+    *,
+    destination: Path | None = None,
+    fmt: str = "json",
+    template: str = "minimal",
+    description: str = "",
+    author: str = "",
+) -> tuple[Path, list[str]]:
+    """Create a new extension project.
+
+    Returns ``(project_root, written_relative_paths)``.
+    """
+    pkg_name = normalize_name(name)
+    if template != "minimal":
+        raise ScaffoldError(f"unknown template '{template}' (available: minimal)")
+
+    try:
+        project_dir = (destination or Path.cwd()) / name
+    except TypeError as exc:
+        raise ScaffoldError(f"invalid destination: {destination!r}") from exc
+
+    project_dir = project_dir.resolve()
+    if project_dir.exists():
+        has_entries = any(project_dir.iterdir())
+        if has_entries:
+            raise ScaffoldError(f"destination {project_dir} already exists and is not empty")
+    project_dir.mkdir(parents=True, exist_ok=True)
+
+    template_root = TEMPLATES_DIR / "extension"
+    if not template_root.is_dir():
+        raise ScaffoldError(f"template tree missing at {template_root}")
+
+    selected_manifest = f"manifest.{fmt}.j2"
+    if fmt not in {"json", "xml"}:
+        raise ScaffoldError(f"unknown manifest format '{fmt}' (json|xml)")
+
+    values = build_values(
+        pkg_name,
+        description=description,
+        author=author,
+    )
+
+    written: list[str] = []
+    for src in _walk_templates(template_root):
+        rel = src.relative_to(template_root)
+        if rel.name == selected_manifest:
+            rel = Path("manifest." + fmt)
+        elif rel.name.startswith("manifest.") and rel.suffix == ".j2":
+            continue  # the unselected manifest variant is not emitted
+        rel_text = render(str(rel), values)
+        target = project_dir / rel_text
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(render(src.read_text(encoding="utf-8"), values), encoding="utf-8")
+        written.append(str(target.relative_to(project_dir)))
+
+    return project_dir, written

resolve_script/semver.py

@@ -0,0 +1,236 @@
+"""Minimal SemVer 2.0 parsing and range matching (no external deps)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_VERSION_RE = re.compile(
+    r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)"
+    r"(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?"
+    r"(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$"
+)
+
+
+class SemVerError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Version:
+    major: int
+    minor: int = 0
+    patch: int = 0
+    prerelease: str = ""
+
+    def __post_init__(self) -> None:
+        if self.major < 0 or self.minor < 0 or self.patch < 0:
+            raise SemVerError(f"negative version component: {self!r}")
+
+    @classmethod
+    def parse(cls, text: str) -> Version:
+        match = _VERSION_RE.match(text.strip())
+        if not match:
+            raise SemVerError(f"'{text}' is not a valid SemVer version")
+        return cls(
+            major=int(match.group(1)),
+            minor=int(match.group(2)),
+            patch=int(match.group(3)),
+            prerelease=match.group(4) or "",
+        )
+
+    @staticmethod
+    def _pre_key(value: str) -> tuple[int, ...]:
+        # numeric identifiers sort lower than alphanumeric ones
+        result: list[int] = []
+        for part in value.split("."):
+            if part.isdigit():
+                result.append(0)
+                result.append(int(part))
+            else:
+                result.append(1)
+                result.append(len(part))
+                result.append(sum(ord(c) for c in part))
+        return tuple(result)
+
+    def _release_key(self) -> tuple:
+        return (self.major, self.minor, self.patch)
+
+    def __lt__(self, other: Version) -> bool:  # noqa: D105
+        a, b = self._release_key(), other._release_key()
+        if a != b:
+            return a < b
+        if self.prerelease == other.prerelease:
+            return False
+        if not self.prerelease:
+            return False  # release > prerelease
+        if not other.prerelease:
+            return True
+        return Version._pre_key(self.prerelease) < Version._pre_key(other.prerelease)
+
+    def __le__(self, other: Version) -> bool:  # noqa: D105
+        return self == other or self < other
+
+    def __gt__(self, other: Version) -> bool:  # noqa: D105
+        return not (self <= other)
+
+    def __ge__(self, other: Version) -> bool:  # noqa: D105
+        return not (self < other)
+
+    def __str__(self) -> str:
+        text = f"{self.major}.{self.minor}.{self.patch}"
+        if self.prerelease:
+            text += f"-{self.prerelease}"
+        return text
+
+
+# ---------------------------------------------------------------------------
+# ranges
+# ---------------------------------------------------------------------------
+_COMPARATOR_RE = re.compile(
+    r"^\s*(>=|<=|>|<|=|~|\^)?\s*"
+    r"((0|[1-9]\d*)(?:\.(0|[1-9]\d*))?(?:\.(0|[1-9]\d*))?(?:-[0-9A-Za-z.\-]+)?)"
+    r"\s*$"
+)
+
+
+def _parse_lenient(raw: str) -> Version:
+    if _VERSION_RE.match(raw):
+        return Version.parse(raw)
+    return _first_three(raw)
+
+
+def _comparator_matches(op: str | None, version: Version, raw: str) -> bool:
+    if op == "~":
+        # npm tilde on partials: ~1 => <2.0.0 ; ~1.0 / ~1.2.3 => <1.1.0 / <1.3.0
+        target = _first_three(raw)
+        core_parts = _core_only(raw).split(".")
+        if len(core_parts) == 1:
+            upper = Version(target.major + 1, 0, 0)
+        else:
+            upper = Version(target.major, target.minor + 1, 0)
+        return version >= target and version < upper
+    if op == "^":
+        # ^1.2.3 => >=1.2.3 <2.0.0 ; ^0.2.3 => >=0.2.3 <0.3.0 ; ^0.0.3 => >=0.0.3 <0.0.4
+        target = _first_three(raw)
+        if target.major > 0:
+            upper = Version(target.major + 1, 0, 0)
+        elif target.minor > 0:
+            upper = Version(0, target.minor + 1, 0)
+        else:
+            upper = Version(0, 0, target.patch + 1)
+        return version >= target and version < upper
+
+    core = _core_only(raw)
+    if op in (None, ""):
+        if _has_prerelease(raw):
+            return version == _parse_lenient(raw) or version == Version.parse(core)
+        return version == _parse_lenient(raw)
+
+    target = _parse_lenient(core)
+    # pre-release versions only compare against the same [major,minor,patch]
+    if version.prerelease and version._release_key() != target._release_key():
+        return False
+
+    if op == ">=":
+        return version >= target
+    if op == "<=":
+        return version <= target
+    if op == ">":
+        return version > target
+    if op == "<":
+        return version < target
+    if op == "=":
+        return version == target
+    return version >= target  # ">=x" fallback
+
+
+def _first_three(raw: str) -> Version:
+    parts = raw.replace("-", ".").split(".")[:3]
+    return Version(_int(parts, 0), _int(parts, 1), _int(parts, 2))
+
+
+def _core_only(raw: str) -> str:
+    return raw.split("-")[0].split("+")[0]
+
+
+def _has_prerelease(raw: str) -> bool:
+    return "-" in raw
+
+
+def _int(parts: list[str], index: int) -> int:
+    if len(parts) > index and parts[index]:
+        try:
+            return int(parts[index])
+        except ValueError:
+            return 0
+    return 0
+
+
+def _xy_floor(raw: str) -> Version:
+    parts = raw.replace("-", ".").split(".")
+    pieces: list[int] = []
+    for part in parts:
+        if part in ("x", "X", "*"):
+            break
+        try:
+            pieces.append(int(part))
+        except ValueError:
+            break
+    return Version(pieces[0] if pieces else 0, pieces[1] if len(pieces) > 1 else 0, pieces[2] if len(pieces) > 2 else 0)
+
+
+def _xy_ceil(raw: str) -> Version:
+    parts = raw.replace("-", ".").split(".")
+    major = 0
+    for part in parts:
+        if part.isdigit():
+            major = int(part)
+        else:
+            break
+    return Version(major + 1 if major else 1, 0, 0)
+
+
+def matches(version: Version, range_text: str) -> bool:
+    """True if ``version`` satisfies the npm-style ``range_text``."""
+    range_text = (range_text or "*").strip()
+    if range_text in ("", "*", "x", "X"):
+        return True
+    if _VERSION_RE.match(range_text):
+        return version == Version.parse(range_text)
+    for clause in range_text.replace(",", " ").split():
+        if clause.startswith("-"):
+            continue
+        match = _COMPARATOR_RE.match(clause)
+        if match:
+            op, raw = match.group(1), match.group(2)
+            # handle x-ranges like 1.x or 1
+            if any(c in raw for c in "xX*") or raw.count(".") < 1:
+                lo = _xy_floor(raw)
+                hi = _xy_ceil(raw)
+                return lo <= version < hi
+            if not _comparator_matches(op, version, raw):
+                return False
+        elif "-" in clause and clause.count("-") == 1:
+            lo, hi = clause.split("-")
+            if not (version >= Version.parse(_core_only(lo))):
+                return False
+            if hi.strip() and not (version <= Version.parse(_core_only(hi))):
+                return False
+    return True
+
+
+def pick_best(candidates: list[str], range_text: str | None = None) -> str | None:
+    """Return the highest version satisfying the range (or the highest overall)."""
+    best: Version | None = None
+    best_text: str | None = None
+    for text in candidates:
+        try:
+            version = Version.parse(text)
+        except SemVerError:
+            continue
+        if range_text and not matches(version, range_text):
+            continue
+        if best is None or version > best:
+            best, best_text = version, text
+    return best_text

resolve_script/sources/__init__.py

@@ -0,0 +1,15 @@
+"""Extension sources: where a package comes from.
+
+Kind matrix (mirrors the design notes):
+
+``path``        a directory on disk (``./dir``, ``../dir``, absolute; ``file:dir``)
+``archive``     a tar.gz/zip downloaded from a URL (or ``file:`` archive)
+``github``      ``owner/repo`` or ``github:owner/repo`` (codeload tarball,
+                ``#semver:<range>``/``#<ref>`` selection)
+``manifest``    a URL pointing at a manifest.json (follows ``release.url``)
+``name``        bare name -> looked up in the known-extensions table
+"""
+
+from .archive import ARCHIVE_SUFFIXES, is_archive_path, unpack_archive  # noqa: F401
+
+__all__ = ["ARCHIVE_SUFFIXES", "is_archive_path", "unpack_archive"]

resolve_script/sources/archive.py

@@ -0,0 +1,82 @@
+"""tar.gz / zip unpacking with a single-top-level-dir strip and path safety."""
+
+from __future__ import annotations
+
+import tarfile
+import zipfile
+from pathlib import Path
+
+
+class ArchiveError(RuntimeError):
+    pass
+
+
+ARCHIVE_SUFFIXES = (".tgz", ".tar.gz", ".zip")
+
+
+def is_archive_path(path: str | Path) -> bool:
+    text = str(path).lower()
+    return (
+        text.endswith(".tar.gz")
+        or text.endswith(".tgz")
+        or text.endswith(".zip")
+    )
+
+
+def _safe_members(names: list[str]) -> None:
+    for name in names:
+        if name.startswith(("/", "\\")) or ".." in Path(name).parts:
+            raise ArchiveError(f"archive contains unsafe path: {name!r}")
+
+
+def _find_root(candidates: list[str]) -> str:
+    """Return the single root layer, or "" if files sit at the archive root."""
+    roots = sorted({parts[0] for parts in (Path(c).parts for c in candidates) if parts})
+    if len(roots) != 1:
+        return ""
+    root = roots[0]
+    for name in candidates:
+        if Path(name).parts[0] != root:
+            return ""
+    return root
+
+
+def unpack_archive(archive: Path, dest_dir: Path) -> Path:
+    """Extract ``archive`` under ``dest_dir`` and return the package root.
+
+    The package root is the directory (archive root or the single stripped
+    top-level dir) that contains ``manifest.json``.
+    """
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        if str(archive).lower().endswith(".zip"):
+            with zipfile.ZipFile(archive) as zf:
+                names = zf.namelist()
+                _safe_members(names)
+                zf.extractall(dest_dir)
+        else:
+            with tarfile.open(archive, "r:*") as tf:
+                names = tf.getnames()
+                _safe_members(names)
+                tf.extractall(dest_dir, filter="data")
+    except (tarfile.TarError, zipfile.BadZipFile, OSError) as exc:
+        raise ArchiveError(f"failed to unpack {archive}: {exc}") from exc
+
+    if (dest_dir / "manifest.json").is_file():
+        return dest_dir
+    root = _find_root(names)
+    package_root = dest_dir / root if root else dest_dir
+    if not (package_root / "manifest.json").is_file():
+        raise ArchiveError(
+            f"{archive} does not contain a package: no manifest.json "
+            "(expected at the archive root or under a single top-level dir)"
+        )
+    return package_root
+
+
+def make_archive(package_root: Path, dest: Path) -> Path:
+    """Create ``dest`` (tar.gz) from a package dir (used by tests / packaging)."""
+    dest = dest.with_suffix(".tar.gz") if not dest.suffix else dest
+    with tarfile.open(dest, "w:gz") as tf:
+        tf.add(package_root, arcname=package_root.name)
+    return dest

resolve_script/sources/git.py

@@ -0,0 +1,107 @@
+"""GitHub sources: codeload tarball URLs and SemVer tag selection."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..fetch import fetch, fetch_json
+from ..semver import Version, pick_best
+from .archive import unpack_archive
+
+
+class GitSourceError(RuntimeError):
+    pass
+
+
+def codeload_url(owner: str, repo: str, ref: str | None = None) -> str:
+    slug = ref or "HEAD"
+    return f"https://codeload.github.com/{owner}/{repo}/tar.gz/{slug}"
+
+
+def default_branch(owner: str, repo: str) -> str:
+    """Best-effort default branch (falls back to HEAD on failure)."""
+    try:
+        data = fetch_json(f"https://api.github.com/repos/{owner}/{repo}")
+    except Exception:
+        return "HEAD"
+    if isinstance(data, dict):
+        default = data.get("default_branch")
+        if isinstance(default, str) and default:
+            return default
+    return "HEAD"
+
+
+def list_tags(owner: str, repo: str) -> list[str]:
+    """Return release tag names (e.g. ``v1.2.3``) from the GitHub API."""
+    url = f"https://api.github.com/repos/{owner}/{repo}/tags?per_page=100"
+    data = fetch_json(url)
+    if not isinstance(data, list):
+        raise GitSourceError(f"unexpected GitHub tags response for {owner}/{repo}")
+    return [str(item.get("name")) for item in data if isinstance(item, dict)]
+
+
+def resolve_tag(owner: str, repo: str, range_text: str | None, ref: str | None):
+    """Pick the ref to download.
+
+    An explicit ``ref`` wins. Otherwise, with ``#semver:<range>``, the highest
+    tag satisfying the range; with no range, ``HEAD``.
+    """
+    if ref:
+        return ref
+    if not range_text:
+        return "HEAD"
+    tags = list_tags(owner, repo)
+    candidates = [t[1:] if t.startswith("v") else t for t in tags]
+    best = pick_best(candidates, range_text)
+    if best is None:
+        raise GitSourceError(
+            f"no tag of {owner}/{repo} satisfies '{range_text}' "
+            f"(tags: {', '.join(tags) or 'none'})"
+        )
+    if f"v{best}" in tags:
+        return f"v{best}"
+    return best
+
+
+def download_github(
+    owner: str,
+    repo: str,
+    *,
+    ref: str | None = None,
+    range_text: str | None = None,
+    cache_dir: Path,
+) -> tuple[Path, str]:
+    """Download the codeload tarball and unpack it.
+
+    Returns ``(package_root, integrity_sha256)``.
+    """
+    selected = resolve_tag(owner, repo, range_text, ref)
+    if selected and selected != "HEAD" and selected.startswith("v"):
+        # keep the v-prefixed tag if that is what the repo calls it
+        pass
+    url = codeload_url(owner, repo, None if selected == "HEAD" else selected)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    archive = cache_dir / f"{owner}-{repo}-{selected or 'head'}.tgz"
+    from ..fetch import FetchError, sha256_file
+
+    try:
+        if not archive.is_file():
+            fetch(url=url, dest=archive)
+    except FetchError as exc:
+        raise GitSourceError(str(exc)) from exc
+    package_dir = cache_dir / f"{owner}-{repo}-{selected or 'head'}"
+    if not (package_dir / "manifest.json").is_file():
+        package_dir = unpack_archive(archive, cache_dir / "unpacked" / f"{owner}-{repo}-{selected}")
+    return package_dir, sha256_file(archive)
+
+
+def tags_have_version(tags: list[str]) -> bool:
+    return any(_is_version_tag(t) for t in tags)
+
+
+def _is_version_tag(tag: str) -> bool:
+    try:
+        Version.parse(tag[1:] if tag.startswith("v") else tag)
+        return True
+    except Exception:
+        return False

resolve_script/sources/known.py

@@ -0,0 +1,47 @@
+"""Known-extension table and standard naming conventions (Tauri-style)."""
+
+from __future__ import annotations
+
+# The canonical conventions (used to find a package from a bare name):
+#   * dashes/underscores are treated alike when matching a bare name;
+#   * a bare name resolves to github:owner/<resolvescript-<name>> first,
+#     then github:owner/<name>;
+#   * registered extensions live here with their canonical source.
+CONVENTIONS = (
+    # "resolvescript-<name>"
+    "resolvescript",
+)
+
+_TABLE: dict[str, dict[str, str]] = {
+    # name: canonical source + short description
+    "hello": {"source": "github:OseMine/resolvescript-hello", "desc": "Hello-world demo extension"},
+}
+
+
+def known_names() -> list[str]:
+    return sorted(_TABLE)
+
+
+def lookup(name: str) -> dict | None:
+    """Find a known extension by name (case/dash/underscore-insensitive)."""
+    needle = name.lower().replace("-", "_").replace(" ", "_")
+    for key, entry in _TABLE.items():
+        if key.lower().replace("-", "_") == needle:
+            return {"name": key, **entry}
+    return None
+
+
+def search(query: str) -> list[dict]:
+    q = query.lower()
+    return [
+        {"name": name, **entry}
+        for name, entry in _TABLE.items()
+        if q in name.lower() or q in entry["desc"].lower() or q in entry["source"].lower()
+    ]
+
+
+def canonical_source(name: str) -> str | None:
+    found = lookup(name)
+    if found:
+        return found["source"]
+    return None

resolve_script/sources/release.py

@@ -0,0 +1,55 @@
+"""GitHub release-asset URLs from ``manifest.release``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class ReleaseError(RuntimeError):
+    pass
+
+
+@dataclass
+class ReleaseSpec:
+    url: str = ""
+    owner: str | None = None
+    repo: str | None = None
+    asset: str | None = None
+    tag: str | None = None
+
+    @classmethod
+    def from_data(cls, data: dict) -> ReleaseSpec:
+        owner = data.get("owner")
+        repo = data.get("repo")
+        return cls(
+            url=str(data.get("url", "")) or None,
+            owner=str(owner) if owner else None,
+            repo=str(repo) if repo else None,
+            asset=(data.get("asset") and str(data["asset"])) or None,
+            tag=(data.get("tag") and str(data["tag"])) or None,
+        )
+
+
+def asset_download_url(spec: ReleaseSpec, manifest_name: str, version: str) -> str:
+    """Resolve ``spec`` to a direct-download URL.
+
+    ``manifest.release.url`` wins when present. Otherwise build the GitHub
+    ``releases/latest/download/<asset>`` URL from owner/repo; the asset name
+    defaults to ``<name>-<version>.tgz``.
+    """
+    if spec.url:
+        return spec.url
+    if not spec.owner or not spec.repo:
+        raise ReleaseError(
+            "manifest.release needs 'url' or both 'owner' and 'repo'"
+        )
+    asset = spec.asset or f"{manifest_name}-{version}.tgz"
+    if spec.tag:
+        return (
+            f"https://github.com/{spec.owner}/{spec.repo}"
+            f"/releases/download/{spec.tag}/{asset}"
+        )
+    return (
+        f"https://github.com/{spec.owner}/{spec.repo}"
+        f"/releases/latest/download/{asset}"
+    )