typvend 0.1.0__tar.gz

typvend-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,15 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  prek:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v8.1.0
+      - run: uv sync --group dev
+      - run: uvx prek run -a

typvend-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,48 @@
+name: publish-pypi
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.14"
+      - name: Build distributions
+        run: uv build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sylphy
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

typvend-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - run: uv run pytest

typvend-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Local test outputs
+test_*/
+.pytest_cache/
+
+# Editor / IA agents
+.idea/
+.claude/
+.antigravitycli/

typvend-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

typvend-0.1.0/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.

typvend-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,48 @@
+# 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/justfile

@@ -0,0 +1,20 @@
+# Development commands for typvend
+
+# Run all formatting and linting checks
+check: format lint typecheck test
+
+# Format code using ruff
+format:
+    uv run ruff format .
+
+# Lint code using ruff
+lint:
+    uv run ruff check .
+
+# Run type checking using pyrefly
+typecheck:
+    uv run pyrefly check
+
+# Run unit tests using pytest
+test:
+    uv run pytest

typvend-0.1.0/prek.toml

@@ -0,0 +1,42 @@
+#:schema https://www.schemastore.org/prek.json
+
+exclude = "^.idea/|^uv\\.lock$"
+
+[[repos]]
+repo = "https://github.com/pre-commit/pre-commit-hooks"
+rev = "v6.0.0"
+hooks = [
+  { id = "check-yaml" },
+  { id = "check-toml" },
+  { id = "end-of-file-fixer" },
+  { id = "trailing-whitespace" }
+]
+
+[[repos]]
+repo = "local"
+hooks = [
+  {
+    id = "ruff-format",
+    name = "ruff-format",
+    entry = "uv run ruff format",
+    language = "system",
+    pass_filenames = false,
+    always_run = true
+  },
+  {
+    id = "ruff-check",
+    name = "ruff-check",
+    entry = "uv run ruff check --fix",
+    language = "system",
+    pass_filenames = false,
+    always_run = true
+  },
+  {
+    id = "pyrefly",
+    name = "pyrefly",
+    entry = "uv run pyrefly check",
+    language = "system",
+    pass_filenames = false,
+    always_run = true
+  },
+]

typvend-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "typvend"
+version = "0.1.0"
+description = "Typst Package Vendoring CLI"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+dependencies = [
+    "platformdirs>=4.9",
+    "niquests>=3.18.0",
+]
+
+[project.scripts]
+typvend = "typvend.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.4",
+    "pyrefly>=1.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/typvend"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812", # Conflicts with formatter
+    "ISC001", # Conflicts with formatter
+    "S202", # tarfile.extractall is safe as we use filter/validation
+    "TRY301", # Abstract raise is too pedantic
+    "TRY400", # We explicitly log or swallow tracebacks based on verbose flag
+    "TRY401", # Redundant exception object is preferred for clarity
+    "BLE001", # Graceful top-level exception catching is standard in CLIs
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101", # asserts are standard in pytest
+]
+
+[tool.pyrefly]
+project-includes = [
+    "**/*.py*",
+]

typvend-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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