typvend 0.1.0__py3-none-any.whl

typvend/__init__.py

@@ -0,0 +1,7 @@
+"""typvend - Typst Package Vendoring CLI.
+
+A robust Python utility to scan Typst files and vendor required preview
+packages locally for offline usage.
+"""
+
+__version__ = "0.1.0"

typvend/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for executing the package with python -m typvend."""
+
+from typvend.cli import main
+
+if __name__ == "__main__":
+    main()

typvend/cli.py

@@ -0,0 +1,202 @@
+"""Command-line interface for the typvend tool.
+
+This module sets up the argument parser, handles the subcommands 'add' and 'scan',
+and configures logging.
+"""
+
+import argparse
+import logging
+import re
+import sys
+from pathlib import Path
+
+import niquests
+import platformdirs
+
+from typvend.downloader import download_package
+from typvend.index import resolve_latest_version
+from typvend.scanner import scan_path
+
+logger = logging.getLogger("typvend")
+
+
+def get_default_output() -> Path:
+    """Returns the platform-specific default Typst package directory.
+
+    Returns:
+        A Path object pointing to the system package directory.
+    """
+    return platformdirs.user_data_path("typst") / "packages"
+
+
+def parse_package_arg(pkg: str) -> tuple[str, str]:
+    """Parses a package argument in format name[@version].
+
+    Args:
+        pkg: A string of the form "name" or "name@version".
+
+    Returns:
+        A tuple (name, version) where version is "latest" if not specified.
+
+    Raises:
+        ValueError: If the package name is empty or contains invalid characters.
+    """
+    if "@" in pkg:
+        parts = pkg.split("@", 1)
+        name = parts[0]
+        version = parts[1] or "latest"
+    else:
+        name = pkg
+        version = "latest"
+
+    if not name or not re.fullmatch(r"[a-zA-Z0-9_-]+", name):
+        msg = f"Invalid package name: '{name}'. Only alphanumeric, hyphens, underscores allowed."
+        raise ValueError(msg)
+
+    return name, version
+
+
+def handle_add(args: argparse.Namespace) -> int:
+    """Handles the 'add' subcommand.
+
+    Args:
+        args: Parsed command-line arguments.
+
+    Returns:
+        0 if all packages were successfully vendored, 1 otherwise.
+    """
+    namespace: str = args.namespace
+    output_dir = Path(args.output) if args.output else get_default_output()
+    force: bool = args.force
+
+    failed = False
+
+    # Type refinement
+    packages: list[str] = args.packages
+
+    for pkg_arg in packages:
+        name, version = parse_package_arg(pkg_arg)
+        try:
+            if version == "latest":
+                logger.info("Resolving latest version for %s...", name)
+                version = resolve_latest_version(name, namespace)
+                logger.info("Latest version resolved to %s", version)
+
+            download_package(
+                name=name,
+                version=version,
+                output_dir=output_dir,
+                namespace=namespace,
+                force=force,
+            )
+        except (ValueError, TypeError, niquests.RequestException, OSError):
+            failed = True
+            logger.error("Error vendoring package '%s'", pkg_arg, exc_info=args.verbose)
+
+    return 1 if failed else 0
+
+
+def handle_scan(args: argparse.Namespace) -> int:
+    """Handles the 'scan' subcommand.
+
+    Args:
+        args: Parsed command-line arguments.
+
+    Returns:
+        0 if all discovered packages were successfully vendored, 1 otherwise.
+    """
+    namespace: str = args.namespace
+    output_dir = Path(args.output) if args.output else get_default_output()
+    force: bool = args.force
+    scan_target = Path(args.path)
+
+    if not scan_target.exists():
+        logger.error("Scan path does not exist: %s", scan_target)
+        return 1
+
+    logger.info("Scanning %s for package imports...", scan_target)
+    packages = scan_path(scan_target, namespace)
+    logger.info("Discovered %d package(s): %s", len(packages), packages)
+
+    if not packages:
+        logger.info("No packages found to vendor.")
+        return 0
+
+    failed = False
+    for name, version in sorted(packages):
+        try:
+            download_package(
+                name=name,
+                version=version,
+                output_dir=output_dir,
+                namespace=namespace,
+                force=force,
+            )
+        except (ValueError, TypeError, niquests.RequestException, OSError):
+            failed = True
+            logger.error("Error vendoring package '%s:%s'", name, version, exc_info=args.verbose)
+
+    return 1 if failed else 0
+
+
+def main() -> None:
+    """Main entry point for the CLI."""
+    parent_parser = argparse.ArgumentParser(add_help=False)
+    parent_parser.add_argument(
+        "-o", "--output", help="Custom output directory for vendored packages"
+    )
+    parent_parser.add_argument(
+        "--namespace",
+        default="preview",
+        help="Package namespace (default: preview)",
+    )
+    parent_parser.add_argument(
+        "-f",
+        "--force",
+        action="store_true",
+        help="Re-download package even if destination already exists",
+    )
+    parent_parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Enable verbose output logging",
+    )
+
+    parser = argparse.ArgumentParser(description="typvend — Typst Package Vendoring CLI")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    add_parser = subparsers.add_parser(
+        "add", parents=[parent_parser], help="Add explicit package(s) by name"
+    )
+    add_parser.add_argument(
+        "packages",
+        nargs="+",
+        help="Package name(s) optionally with version (e.g. fontawesome or fontawesome@0.6.0)",
+    )
+
+    scan_parser = subparsers.add_parser(
+        "scan",
+        parents=[parent_parser],
+        help="Scan files/directories and vendor all discovered package imports",
+    )
+    scan_parser.add_argument("path", help="Path to file or directory to scan for imports")
+
+    args = parser.parse_args()
+
+    # Configure logging
+    log_level = logging.INFO if args.verbose else logging.WARNING
+    logging.basicConfig(
+        level=log_level,
+        format="%(levelname)s: %(message)s",
+    )
+    logger.setLevel(log_level)
+
+    if args.command == "add":
+        code = handle_add(args)
+    elif args.command == "scan":
+        code = handle_scan(args)
+    else:
+        code = 1
+
+    sys.exit(code)

typvend/downloader.py

@@ -0,0 +1,88 @@
+"""Module for downloading and extracting Typst packages.
+
+This module provides functions to fetch a package tarball from the Typst
+repository, verify its paths to prevent directory traversal, and extract
+its contents to the local vendor directory.
+"""
+
+import io
+import logging
+import sys
+import tarfile
+from pathlib import Path
+
+import niquests
+
+from typvend import __version__
+
+logger = logging.getLogger(__name__)
+
+
+def download_package(
+    name: str,
+    version: str,
+    output_dir: Path,
+    namespace: str = "preview",
+    *,
+    force: bool = False,
+) -> bool:
+    """Downloads and extracts a Typst package to the local directory.
+
+    Args:
+        name: The name of the package.
+        version: The package version (e.g. "0.6.0").
+        output_dir: The base vendor output directory.
+        namespace: The namespace of the package (e.g. "preview").
+        force: If True, overwrite the package even if it already exists.
+
+    Returns:
+        True if the package was downloaded and extracted, False if it was
+        skipped because it already exists and force was False.
+
+    Raises:
+        ValueError: If a directory traversal is detected in the tarball.
+        niquests.RequestException: If the package download fails.
+    """
+    dest_dir = output_dir / namespace / name / version
+    if dest_dir.exists() and not force:
+        logger.info(
+            "Skipping package %s:%s (already exists at %s)",
+            name,
+            version,
+            dest_dir,
+        )
+        return False
+
+    url = f"https://packages.typst.org/{namespace}/{name}-{version}.tar.gz"
+    logger.info("Downloading %s...", url)
+    headers = {"User-Agent": f"typvend/{__version__}"}
+
+    try:
+        response = niquests.get(url, headers=headers, timeout=30)
+        response.raise_for_status()
+        content = response.content
+        if not content:
+            msg = f"Failed to download package: no content received from {url}"
+            raise ValueError(msg)
+    except niquests.RequestException as e:
+        logger.error("Failed to download package %s:%s: %s", name, version, e)
+        raise
+
+    logger.info("Extracting %s to %s...", name, dest_dir)
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest_abs = dest_dir.resolve()
+
+    tar_data = io.BytesIO(content)
+    with tarfile.open(fileobj=tar_data, mode="r:gz") as tar:
+        if sys.version_info >= (3, 12):
+            tar.extractall(path=dest_dir, filter="data")
+        else:
+            for member in tar.getmembers():
+                member_path = (dest_dir / member.name).resolve()
+                if dest_abs not in member_path.parents and member_path != dest_abs:
+                    msg = f"Attempted directory traversal in tarball: {member.name}"
+                    raise ValueError(msg)
+            tar.extractall(path=dest_dir)
+
+    logger.info("Successfully vendored %s:%s", name, version)
+    return True

typvend/index.py

@@ -0,0 +1,98 @@
+"""Module for fetching and parsing the Typst packages index.
+
+This module provides functions to fetch the official package list and resolve
+the latest version for any given package name.
+"""
+
+from typing import Any
+
+import niquests
+
+from typvend import __version__
+
+# In-memory cache for index.json requests. Key is namespace.
+_INDEX_CACHE: dict[str, list[dict[str, Any]]] = {}
+
+
+def fetch_index(namespace: str = "preview") -> list[dict[str, Any]]:
+    """Fetches the Typst package index for the given namespace.
+
+    Args:
+        namespace: The package namespace, e.g. "preview".
+
+    Returns:
+        A list of dictionaries containing package metadata.
+
+    Raises:
+        ValueError: If the response cannot be parsed or is invalid.
+    """
+    if namespace in _INDEX_CACHE:
+        return _INDEX_CACHE[namespace]
+
+    url = f"https://packages.typst.org/{namespace}/index.json"
+    headers = {"User-Agent": f"typvend/{__version__}"}
+
+    try:
+        response = niquests.get(url, headers=headers, timeout=15)
+        response.raise_for_status()
+        data = response.json()
+    except niquests.RequestException as e:
+        msg = f"Failed to fetch package index from {url}: {e}"
+        raise ValueError(msg) from e
+
+    if not isinstance(data, list):
+        msg = f"Expected index.json to be a list, got {type(data)}"
+        raise TypeError(msg)
+
+    _INDEX_CACHE[namespace] = data
+    return data
+
+
+def parse_semver(version_str: str) -> tuple[int, int, int] | None:
+    """Parses a semver version string into a tuple of integers.
+
+    Args:
+        version_str: A string of the form "major.minor.patch".
+
+    Returns:
+        A tuple (major, minor, patch), or None if the version is invalid.
+    """
+    parts = version_str.split(".")
+    if len(parts) != 3:  # noqa: PLR2004
+        return None
+    try:
+        return int(parts[0]), int(parts[1]), int(parts[2])
+    except ValueError:
+        return None
+
+
+def resolve_latest_version(pkg_name: str, namespace: str = "preview") -> str:
+    """Resolves the latest version of a package from the Typst packages index.
+
+    Args:
+        pkg_name: The name of the package.
+        namespace: The namespace to search.
+
+    Returns:
+        The latest version string (e.g. "0.6.0").
+
+    Raises:
+        ValueError: If the package is not found in the index.
+        TypeError: If the upstream index response has an unexpected type.
+    """
+    index_data = fetch_index(namespace)
+    versions: list[tuple[tuple[int, int, int], str]] = []
+    for pkg in index_data:
+        if pkg.get("name") == pkg_name:
+            version = pkg.get("version")
+            if isinstance(version, str):
+                parsed = parse_semver(version)
+                if parsed is not None:
+                    versions.append((parsed, version))
+
+    if not versions:
+        msg = f"Package '{pkg_name}' not found in namespace '{namespace}'"
+        raise ValueError(msg)
+
+    versions.sort(key=lambda v: v[0])
+    return versions[-1][1]

typvend/scanner.py

@@ -0,0 +1,62 @@
+"""Module for scanning Typst files to find imported packages.
+
+This module provides functionality to scan single .typ files or recursively
+scan directories to identify all referenced packages in a given namespace.
+"""
+
+import logging
+import re
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def scan_file(file_path: Path, namespace: str = "preview") -> set[tuple[str, str]]:
+    """Scans a single file for package imports in the given namespace.
+
+    Matches imports like `@<namespace>/<pkg>:<version>`.
+
+    Args:
+        file_path: The path of the file to scan.
+        namespace: The namespace to search for (e.g. "preview").
+
+    Returns:
+        A set of tuples (package_name, version).
+    """
+    found: set[tuple[str, str]] = set()
+    pattern = re.compile(rf"@{re.escape(namespace)}/([a-zA-Z0-9_-]+):(\d+\.\d+\.\d+)")
+
+    try:
+        content = file_path.read_text(encoding="utf-8", errors="ignore")
+    except OSError as e:
+        logger.warning("Could not read file %s: %s", file_path, e)
+        return found
+
+    for match in pattern.finditer(content):
+        pkg_name = match.group(1)
+        version = match.group(2)
+        found.add((pkg_name, version))
+
+    return found
+
+
+def scan_path(path: Path, namespace: str = "preview") -> set[tuple[str, str]]:
+    """Scans a file or recursively scans a directory for package imports.
+
+    Args:
+        path: Path to a file or directory.
+        namespace: The namespace to search for (e.g. "preview").
+
+    Returns:
+        A set of tuples (package_name, version).
+    """
+    found: set[tuple[str, str]] = set()
+
+    if path.is_file():
+        return scan_file(path, namespace)
+
+    if path.is_dir():
+        for file in path.rglob("*.typ"):
+            found.update(scan_file(file, namespace))
+
+    return found

typvend-0.1.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: typvend
+Version: 0.1.0
+Summary: Typst Package Vendoring CLI
+License: MIT License
+        
+        Copyright (c) 2026 Diego Alvarez S.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: niquests>=3.18.0
+Requires-Dist: platformdirs>=4.9
+Description-Content-Type: text/markdown
+
+# typvend — Typst Package Vendoring CLI
+
+`typvend` is a lightweight Python CLI utility designed to vendor official Typst packages locally for offline development, sandboxed builds, or containerized production CI/CD workflows.
+
+## Why?
+
+Typst downloads packages on the fly at compile time with no official way to pre-download them.
+This can be problematic for offline compilation and read-only production environments (like containers).
+The solution is to either run the compilation once to fetch the packages or download them manually.
+
+`typvend` simplifies this, downloading packages to the default Typst cache path or any directory you choose (then point Typst to it via `--package-cache-path`), in two ways:
+- **Explicit:** `add <pkg>[@<version>]` — download specific packages by name, with a version or `@latest`.
+- **Scan:** recursively find all `@preview/<pkg>:<version>` imports in `.typ` files and vendor them in one go.
+
+## Usage
+
+```bash
+# Install and run instantly using uvx / pipx
+uvx typvend --help
+```
+
+Global options:
+- `-o`, `--output DIR` — Custom directory to extract packages (defaults to native OS Typst search path).
+- `--namespace NS` — Custom namespace (defaults to `preview`).
+- `-f`, `--force` — Re-download package even if it already exists.
+- `-v`, `--verbose` — Enable verbose output logs.
+
+### 1. Adding Packages Explicitly
+
+```bash
+# Download latest version of fontawesome
+uvx typvend add fontawesome
+
+# Download specific versions
+uvx typvend add fontawesome@0.5.0 cetz
+```
+
+### 2. Scanning Project Directories
+
+Recursively searches a file or directory for package imports and vendors all discovered packages in one command:
+
+```bash
+# Scan a templates directory and output packages to typst cache folder
+uvx typvend scan ./templates
+
+# Scan and output to a custom directory (e.g. for Docker cache stages)
+uvx typvend scan ./templates --output /typst-packages
+```

typvend-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+typvend/__init__.py,sha256=RPIBAOSE283x37HKTTCYw5j99UkxQu5Ct7ODMiwNdtA,178
+typvend/__main__.py,sha256=k60UlPZkYvsMv1yayg6Cn6_iBUHL5FAkmCel_PtHH9k,137
+typvend/cli.py,sha256=059GD-lVh3n1Pn3YGvacTvj3J5COUy5vGOoSd3y2jrw,5888
+typvend/downloader.py,sha256=zx_OsybLergWRYLrjNpgDan899sQB5cc0IZ_uLFqUmc,2902
+typvend/index.py,sha256=rai9B873qYTpd-wS_Mv0mK6WJcZSGMLkI03lNzW0P2w,2977
+typvend/scanner.py,sha256=osFxJvqGNkyOv-qwQQChLAieo3IRv3R8M5O63gl8Nio,1796
+typvend-0.1.0.dist-info/METADATA,sha256=KfJ6RFuxB9f2HqsdU22xMjMUFbc17lQcIHODMLPZSbo,3388
+typvend-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+typvend-0.1.0.dist-info/entry_points.txt,sha256=7n2Xt5tKAGDXJ1Z2qoocCrINRroJ9MhNkYK77q8Tyks,45
+typvend-0.1.0.dist-info/licenses/LICENSE,sha256=Y4U8gNrx2iAql71iNTZWdpNzYWBvoF0KZKVTM_cCfHQ,1073
+typvend-0.1.0.dist-info/RECORD,,

typvend-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

typvend-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+typvend = typvend.cli:main

typvend-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diego Alvarez S.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.