resolvescript 0.1.2__py3-none-any.whl → 0.1.4a0__py3-none-any.whl

ResolveScript/__init__.py

@@ -0,0 +1,366 @@
+"""ResolveScript — script framework for DaVinci Resolve.
+
+ResolveScript is both a CLI and a normal Python package, so you can drive
+every feature directly from a script or an interactive session.
+
+Quick start — create and inspect a new script project::
+
+    import ResolveScript as rs
+
+    root, written = rs.scaffold_project(
+        "my-tool", destination=".", fmt="json", template="default"
+    )
+    print(root, written)
+
+    issues = rs.analyze_project(root)
+    for issue in issues:
+        print(issue)
+
+    cfg = rs.config_from_manifest(root / "resolve-script.manifest.json")
+    result = rs.consolidate(cfg)
+    print(result.target)      # single-file build
+    print(result.sources)     # files folded into the build
+
+Borrow a ``Source`` spec from a known GitHub project::
+
+    import ResolveScript as rs
+
+    print(rs.lookup("hello"))          # canonical source for a known name
+    values = rs.build_values("my-tool")  # template substition values
+
+Sit scripts in the Resolve environment::
+
+    from ResolveScript.sandbox import build_default_env, fake_resolve_module
+    from ResolveScript.install import install_project
+
+    env = build_default_env()
+    fake_resolve_module(env)           # injects a fake ``resolve`` module
+    install_project(env, run_smoke=True, root=".")
+
+Every public name is available both at the package root and from its owning
+module, e.g. ``ResolveScript.consolidate`` is also the top-level
+``consolidate`` function.
+
+Subpackages ship their own convenience imports:
+
+* ``ResolveScript.manifest``  — manifest model, loaders, validators
+* ``ResolveScript.sandbox``   — mock Resolve API, smoke runs, REPL
+* ``ResolveScript.sources``   — archive/git/known-source helpers
+* ``ResolveScript.install``   — install, registry and target resolution
+"""
+
+from __future__ import annotations
+
+from ._version import __version__, get_version
+
+# --- pipeline ----------------------------------------------------------
+from .analyze import KNOWN_ROOTS, Analysis, Issue, analyze_project, issues_to_json
+
+# --- config ------------------------------------------------------------
+from .config import (
+    allow_remote,
+    is_editable_install,
+    normalize_path,
+    plugins_dir,
+    python_spec,
+    scripts_root_override,
+    user_config_dir,
+)
+from .consolidate import (
+    BuildConfig,
+    ConsolidateError,
+    ConsolidateResult,
+    config_from_manifest,
+    consolidate,
+    summarize,
+)
+
+# --- fetch / CLI -------------------------------------------------------
+from .fetch import Fetched, FetchError, fetch, fetch_json, sha256_file
+
+# --- install -----------------------------------------------------------
+from .install import (
+    REGISTRY_REL,
+    SCHEMA_VERSION,
+    InstalledFile,
+    InstallError,
+    InstallOptions,
+    InstallResult,
+    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,
+)
+
+# --- manifest ----------------------------------------------------------
+from .manifest import (
+    TARGET_SUGGESTIONS,
+    Compat,
+    ConsolidateConfig,
+    InstallConfig,
+    Manifest,
+    ManifestError,
+    Release,
+    Target,
+    dumps,
+    is_valid_semver,
+    load_manifest,
+    loads,
+    manifest_from_dict,
+    validate_manifest,
+    validate_manifest_or_throw,
+    validate_target,
+)
+from .package import PackageError, PackageResult, package_project
+
+# --- spec / resolver ---------------------------------------------------
+from .resolver import (
+    Resolved,
+    ResolveError,
+    lockfile_satisfies,
+    resolve_spec,
+)
+
+# --- sandbox -----------------------------------------------------------
+from .sandbox import (
+    DEFAULT_PROJECT,
+    FUSION_SCRIPT_MODULE,
+    FakeClip,
+    FakeComp,
+    FakeFolder,
+    FakeFusion,
+    FakeKey,
+    FakeMediaPool,
+    FakeMediaPoolItem,
+    FakeProject,
+    FakeProjectManager,
+    FakeResolve,
+    FakeSpline,
+    FakeStroke,
+    FakeTimeline,
+    FakeTool,
+    SmokeCheck,
+    SmokeResult,
+    build_default_env,
+    default_namespace,
+    discover_exports,
+    fake_resolve_module,
+    install_fake_resolve,
+    load_built_module,
+    load_source_module,
+    purge_module,
+    run_smoke,
+    start_repl,
+)
+
+# --- scaffold ----------------------------------------------------------
+from .scaffold import (
+    DEFAULT_VERSION,
+    TEMPLATES_DIR,
+    ScaffoldError,
+    build_values,
+    normalize_name,
+    render,
+    scaffold_project,
+)
+from .semver import SemVerError, Version, matches, pick_best
+
+# --- sources -----------------------------------------------------------
+from .sources import (
+    ARCHIVE_SUFFIXES,
+    CONVENTIONS,
+    ArchiveError,
+    GitSourceError,
+    ReleaseError,
+    ReleaseSpec,
+    asset_download_url,
+    canonical_source,
+    codeload_url,
+    default_branch,
+    download_github,
+    is_archive_path,
+    known_names,
+    list_tags,
+    lookup,
+    make_archive,
+    resolve_tag,
+    search,
+    tags_have_version,
+    unpack_archive,
+)
+from .spec import Spec, SpecError, parse_specifier
+from .workspace import (
+    WORKSPACE_FILE,
+    WorkspaceError,
+    add_dependency,
+    has_workspace,
+    read_workspace,
+    remove_dependency,
+    save,
+    workspace_path,
+    write_workspace,
+)
+
+__all__ = [
+    # version
+    "__version__",
+    "get_version",
+    # manifest
+    "Compat",
+    "ConsolidateConfig",
+    "InstallConfig",
+    "Manifest",
+    "ManifestError",
+    "Release",
+    "TARGET_SUGGESTIONS",
+    "Target",
+    "dumps",
+    "is_valid_semver",
+    "load_manifest",
+    "loads",
+    "manifest_from_dict",
+    "validate_manifest",
+    "validate_manifest_or_throw",
+    "validate_target",
+    # sources
+    "ARCHIVE_SUFFIXES",
+    "CONVENTIONS",
+    "ArchiveError",
+    "GitSourceError",
+    "ReleaseError",
+    "ReleaseSpec",
+    "asset_download_url",
+    "canonical_source",
+    "codeload_url",
+    "default_branch",
+    "download_github",
+    "is_archive_path",
+    "known_names",
+    "list_tags",
+    "lookup",
+    "make_archive",
+    "resolve_tag",
+    "search",
+    "tags_have_version",
+    "unpack_archive",
+    # install
+    "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",
+    # sandbox
+    "DEFAULT_PROJECT",
+    "FUSION_SCRIPT_MODULE",
+    "FakeClip",
+    "FakeComp",
+    "FakeFolder",
+    "FakeFusion",
+    "FakeKey",
+    "FakeMediaPool",
+    "FakeMediaPoolItem",
+    "FakeProject",
+    "FakeProjectManager",
+    "FakeResolve",
+    "FakeSpline",
+    "FakeStroke",
+    "FakeTimeline",
+    "FakeTool",
+    "SmokeCheck",
+    "SmokeResult",
+    "build_default_env",
+    "default_namespace",
+    "discover_exports",
+    "fake_resolve_module",
+    "install_fake_resolve",
+    "load_built_module",
+    "load_source_module",
+    "purge_module",
+    "run_smoke",
+    "start_repl",
+    # config
+    "allow_remote",
+    "is_editable_install",
+    "normalize_path",
+    "plugins_dir",
+    "python_spec",
+    "scripts_root_override",
+    "user_config_dir",
+    # spec / resolver
+    "ResolveError",
+    "Resolved",
+    "lockfile_satisfies",
+    "resolve_spec",
+    "SemVerError",
+    "Version",
+    "matches",
+    "pick_best",
+    "Spec",
+    "SpecError",
+    "parse_specifier",
+    "WORKSPACE_FILE",
+    "WorkspaceError",
+    "add_dependency",
+    "has_workspace",
+    "read_workspace",
+    "remove_dependency",
+    "save",
+    "workspace_path",
+    "write_workspace",
+    # pipeline
+    "KNOWN_ROOTS",
+    "Analysis",
+    "Issue",
+    "analyze_project",
+    "issues_to_json",
+    "BuildConfig",
+    "ConsolidateError",
+    "ConsolidateResult",
+    "config_from_manifest",
+    "consolidate",
+    "summarize",
+    "PackageError",
+    "PackageResult",
+    "package_project",
+    # scaffold
+    "DEFAULT_VERSION",
+    "TEMPLATES_DIR",
+    "ScaffoldError",
+    "build_values",
+    "normalize_name",
+    "render",
+    "scaffold_project",
+    # fetch
+    "Fetched",
+    "FetchError",
+    "fetch",
+    "fetch_json",
+    "sha256_file",
+]

ResolveScript/_version.py

@@ -0,0 +1,8 @@
+"""Package version metadata (imported by ``ResolveScript.__init__``)."""
+
+__version__ = "0.1.4-alpha"
+
+
+def get_version() -> str:
+    """Return the installed ``resolvescript`` version string."""
+    return __version__

{resolve_script → ResolveScript}/cli.py

@@ -429,6 +429,7 @@ def _cmd_manage_remove(args: argparse.Namespace) -> int:
     import shutil
 
     from .install.discovery import target_dir
+    from .install.installer import InstallError, validate_registry_name, validate_registry_relpath
     from .install.registry import get_extension, read_registry, remove_entry
 
     scripts_root = _resolve_scripts_root(args.scripts_root)
@@ -441,17 +442,27 @@ def _cmd_manage_remove(args: argparse.Namespace) -> int:
         )
         return 1
     as_directory = bool(entry.get("as_directory", True))
-    key = entry.get("id") or args.name
+    try:
+        key = validate_registry_name(entry.get("id") or args.name)
+        container_name = validate_registry_name(entry.get("name") or key)
+    except InstallError as exc:
+        print(f"resolvescript: manage remove: {exc}", file=sys.stderr)
+        return 1
     for target in entry.get("targets", []):
         base = target_dir(scripts_root, target)
         if as_directory:
-            container = base / (entry.get("name") or key)
+            container = base / container_name
             if container.is_dir():
                 shutil.rmtree(container)
                 print(f"removed {container}")
         else:
-            for rel in entry.get("files", []):
-                path = base / str(rel)
+            for raw_rel in entry.get("files", []):
+                try:
+                    rel = validate_registry_relpath(str(raw_rel))
+                except InstallError as exc:
+                    print(f"resolvescript: manage remove: {exc}", file=sys.stderr)
+                    return 1
+                path = base / rel
                 if path.is_file() or (path.is_symlink() and not path.exists()):
                     path.unlink()
                     print(f"removed {path}")
@@ -495,8 +506,8 @@ def _cmd_test(args: argparse.Namespace) -> int:
         env["RESOLVESCRIPT_BUILT_PATH"] = str(built_file)
         runner = (
             "import os, sys, pathlib\n"
-            "from resolve_script.sandbox.env import install_fake_resolve\n"
-            "from resolve_script.sandbox.loader import load_built_module\n"
+            "from ResolveScript.sandbox.env import install_fake_resolve\n"
+            "from ResolveScript.sandbox.loader import load_built_module\n"
             "install_fake_resolve()\n"
             "if os.environ.get('RESOLVESCRIPT_TARGET') == 'built':\n"
             "    name = os.environ['RESOLVESCRIPT_MODULE']\n"

ResolveScript/fetch.py

@@ -0,0 +1,186 @@
+"""HTTP(S) download + SHA-256 integrity verification (stdlib only)."""
+
+from __future__ import annotations
+
+import hashlib
+import ipaddress
+import socket
+import tempfile
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlparse
+
+# Maximum download size (100 MB) to prevent DoS via unbounded downloads
+_MAX_DOWNLOAD_SIZE = 100 * 1024 * 1024
+
+
+class FetchError(RuntimeError):
+    pass
+
+
+# Non-public address ranges that must never be fetched. Kept explicit (rather
+# than relying on ipaddress.is_private/is_reserved, whose ranges vary across
+# Python versions) so behavior is deterministic. Includes loopback, RFC 1918,
+# CGNAT/shared space, link-local (cloud-metadata), documentation, benchmark and
+# multicast ranges for both address families.
+_BLOCKED_NETS = tuple(
+    ipaddress.ip_network(prefix)
+    for prefix in (
+        "0.0.0.0/8",
+        "10.0.0.0/8",
+        "100.64.0.0/10",
+        "127.0.0.0/8",
+        "169.254.0.0/16",
+        "172.16.0.0/12",
+        "192.0.0.0/24",
+        "192.168.0.0/16",
+        "198.18.0.0/15",
+        "198.51.100.0/24",
+        "203.0.113.0/24",
+        "224.0.0.0/4",
+        "240.0.0.0/4",
+        "255.255.255.255/32",
+        "::/128",
+        "::1/128",
+        "100::/64",
+        "2001:db8::/32",
+        "fc00::/7",
+        "fe80::/10",
+        "ff00::/8",
+    )
+)
+
+
+def _assert_public_host(url: str) -> None:
+    """Reject URLs whose host is not a public internet address (SSRF guard).
+
+    Loopback, private (RFC 1918 / CGNAT / ULA) and link-local addresses
+    (including the cloud-metadata ``169.254.169.254``) are blocked, along
+    with documentation, benchmark, multicast, unspecified and reserved ranges.
+    """
+    host = urlparse(url).hostname
+    if not host:
+        raise FetchError(f"URL has no host: {url!r}")
+    try:
+        addresses = [ipaddress.ip_address(host)]
+    except ValueError:
+        try:
+            resolved = socket.getaddrinfo(host, None)
+        except socket.gaierror as exc:
+            raise FetchError(f"cannot resolve host {host!r}: {exc}") from exc
+        addresses = [ipaddress.ip_address(info[4][0]) for info in resolved]
+    for addr in addresses:
+        if (
+            addr.is_loopback
+            or addr.is_link_local
+            or addr.is_multicast
+            or addr.is_unspecified
+            or any(addr in net for net in _BLOCKED_NETS)
+        ):
+            raise FetchError(
+                f"{host!r} resolves to non-public address {addr} "
+                "(loopback, private or link-local hosts are blocked)"
+            )
+
+
+class _SafeRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Reject redirects to non-http(s) schemes, plaintext downgrades, or
+    non-public hosts (SSRF guard)."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: PLR0913
+        old_scheme = urlparse(req.full_url).scheme.lower()
+        new_scheme = urlparse(newurl).scheme.lower()
+        if new_scheme not in ("http", "https"):
+            raise FetchError(f"redirect to non-http(s) scheme blocked: {newurl!r}")
+        if old_scheme == "https" and new_scheme != "https":
+            raise FetchError(
+                f"refusing to downgrade https connection to plaintext http via redirect: {newurl!r}"
+            )
+        _assert_public_host(newurl)
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+_OPENER = urllib.request.build_opener(_SafeRedirectHandler())
+
+
+@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.
+
+    Only ``http://`` and ``https://`` schemes are allowed; other schemes
+    (e.g. ``file://``, ``ftp://``) raise :class:`FetchError` to prevent
+    local‑file reads and SSRF.
+    """
+    if not url.lower().startswith(("http://", "https://")):
+        raise FetchError(f"only http/https URLs are allowed (got {url!r})")
+    _assert_public_host(url)
+    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 _OPENER.open(url, timeout=timeout) as response:
+                data = response.read(_MAX_DOWNLOAD_SIZE + 1)
+        except Exception as exc:  # URLError, HTTPError, timeout…
+            raise FetchError(f"failed to download {url}: {exc}") from exc
+    finally:
+        socket.setdefaulttimeout(previous)
+    if len(data) > _MAX_DOWNLOAD_SIZE:
+        raise FetchError(f"download exceeds maximum allowed size ({_MAX_DOWNLOAD_SIZE} bytes)")
+    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"))