typst-forge 0.1.0__tar.gz

typst_forge-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: typst-forge
+Version: 0.1.0
+Summary: A local manager for Typst templates and packages
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Typst Forge
+
+Typst Forge is a small local manager for Typst packages and templates.
+
+It can:
+
+- scaffold a new Typst repo with `git`, `typst.toml`, `src`, and `template/` when needed
+- install local development repos into Typst's package directory
+- install release repos from GitHub or any git URL
+- manage installed packages/templates with versioned registry entries
+- fall back between symlink and copy modes for platform-friendly installs
+
+## Install
+
+This repo is meant to be run with `uv`:
+
+```bash
+uv run typst-forge --help
+```
+
+To run it without installing from a checkout, use `uvx`:
+
+```bash
+uvx --from . typst-forge --help
+```
+
+You can also install directly from GitHub:
+
+```bash
+uvx --from git+https://github.com/<owner>/typst-forge typst-forge --help
+```
+
+## Commands
+
+```bash
+typst-forge init ./my-template --kind template --name my-template --version 0.1.0
+typst-forge init ./my-package --kind package --name my-package --version 0.1.0
+typst-forge install ./my-package --link-mode copy
+typst-forge install github:owner/repo@v1.2.3
+typst-forge list
+typst-forge status my-package
+typst-forge update my-package
+typst-forge remove my-package
+```
+
+## Versioning
+
+- local repos use the `typst.toml` package version unless a matching git tag is present at `HEAD`
+- GitHub and other git URLs install from release tags
+- tags can be written as `v1.2.3` or `1.2.3`; the stored Typst version is normalized to `1.2.3`
+- installed entries live under `~/.local/share/typst/packages/<namespace>/<package>/<version>`
+
+## Tests
+
+Run the in-repo test suite with:
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+## Publishing
+
+The GitHub Actions workflow in [.github/workflows/publish.yml](./.github/workflows/publish.yml)
+publishes tagged releases to PyPI with trusted publishing.
+
+Create and push a version tag like `v0.1.0` to trigger it.

typst_forge-0.1.0/README.md

@@ -0,0 +1,66 @@
+# Typst Forge
+
+Typst Forge is a small local manager for Typst packages and templates.
+
+It can:
+
+- scaffold a new Typst repo with `git`, `typst.toml`, `src`, and `template/` when needed
+- install local development repos into Typst's package directory
+- install release repos from GitHub or any git URL
+- manage installed packages/templates with versioned registry entries
+- fall back between symlink and copy modes for platform-friendly installs
+
+## Install
+
+This repo is meant to be run with `uv`:
+
+```bash
+uv run typst-forge --help
+```
+
+To run it without installing from a checkout, use `uvx`:
+
+```bash
+uvx --from . typst-forge --help
+```
+
+You can also install directly from GitHub:
+
+```bash
+uvx --from git+https://github.com/<owner>/typst-forge typst-forge --help
+```
+
+## Commands
+
+```bash
+typst-forge init ./my-template --kind template --name my-template --version 0.1.0
+typst-forge init ./my-package --kind package --name my-package --version 0.1.0
+typst-forge install ./my-package --link-mode copy
+typst-forge install github:owner/repo@v1.2.3
+typst-forge list
+typst-forge status my-package
+typst-forge update my-package
+typst-forge remove my-package
+```
+
+## Versioning
+
+- local repos use the `typst.toml` package version unless a matching git tag is present at `HEAD`
+- GitHub and other git URLs install from release tags
+- tags can be written as `v1.2.3` or `1.2.3`; the stored Typst version is normalized to `1.2.3`
+- installed entries live under `~/.local/share/typst/packages/<namespace>/<package>/<version>`
+
+## Tests
+
+Run the in-repo test suite with:
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+## Publishing
+
+The GitHub Actions workflow in [.github/workflows/publish.yml](./.github/workflows/publish.yml)
+publishes tagged releases to PyPI with trusted publishing.
+
+Create and push a version tag like `v0.1.0` to trigger it.

typst_forge-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "typst-forge"
+version = "0.1.0"
+description = "A local manager for Typst templates and packages"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+typst-forge = "typst_forge.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["typst_forge", "typst_forge.*"]

typst_forge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

typst_forge-0.1.0/src/typst_forge/__init__.py

@@ -0,0 +1,5 @@
+"""Typst Forge: a local manager for Typst packages and templates."""
+
+from .cli import main
+
+__all__ = ["main"]

typst_forge-0.1.0/src/typst_forge/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

typst_forge-0.1.0/src/typst_forge/cli.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .registry import (
+    install_source,
+    installation_status,
+    list_installed_packages,
+    remove_installation,
+    update_installation,
+)
+from .scaffold import scaffold_project
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="typst-forge")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="Create a new Typst project")
+    init_parser.add_argument("path", nargs="?", default=".")
+    init_parser.add_argument("--kind", choices=["template", "package"], default="package")
+    init_parser.add_argument("--name")
+    init_parser.add_argument("--version", default="0.1.0")
+    init_parser.set_defaults(handler=_cmd_init)
+
+    install_parser = subparsers.add_parser(
+        "install", help="Install a local path or GitHub source"
+    )
+    install_parser.add_argument("source")
+    install_parser.add_argument("--namespace", default="local")
+    install_parser.add_argument("--version")
+    install_parser.add_argument("--registry-root", help="Override the Typst packages root")
+    install_parser.add_argument("--cache-root", help="Override the Typst Forge cache root")
+    install_parser.add_argument(
+        "--link-mode",
+        choices=["auto", "symlink", "copy"],
+        default="auto",
+        help="How installed projects should be materialized",
+    )
+    install_parser.add_argument("--force", action="store_true")
+    install_parser.set_defaults(handler=_cmd_install)
+
+    update_parser = subparsers.add_parser(
+        "update", help="Reinstall an installed package or source"
+    )
+    update_parser.add_argument("target")
+    update_parser.add_argument("--namespace", default="local")
+    update_parser.add_argument("--version")
+    update_parser.add_argument("--registry-root", help="Override the Typst packages root")
+    update_parser.add_argument("--cache-root", help="Override the Typst Forge cache root")
+    update_parser.add_argument(
+        "--link-mode",
+        choices=["auto", "symlink", "copy"],
+        default=None,
+        help="How installed projects should be materialized",
+    )
+    update_parser.set_defaults(handler=_cmd_update)
+
+    remove_parser = subparsers.add_parser(
+        "remove", help="Remove an installed package or source"
+    )
+    remove_parser.add_argument("target")
+    remove_parser.add_argument("--namespace", default="local")
+    remove_parser.add_argument("--version")
+    remove_parser.add_argument("--registry-root", help="Override the Typst packages root")
+    remove_parser.set_defaults(handler=_cmd_remove)
+
+    list_parser = subparsers.add_parser("list", help="List installed packages and templates")
+    list_parser.add_argument("--json", action="store_true")
+    list_parser.add_argument("--registry-root", help="Override the Typst packages root")
+    list_parser.set_defaults(handler=_cmd_list)
+
+    status_parser = subparsers.add_parser(
+        "status", help="Show status for an installed package or source"
+    )
+    status_parser.add_argument("target")
+    status_parser.add_argument("--namespace", default="local")
+    status_parser.add_argument("--version")
+    status_parser.add_argument("--registry-root", help="Override the Typst packages root")
+    status_parser.set_defaults(handler=_cmd_status)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.handler(args)
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    root = Path(args.path)
+    name = args.name or root.resolve().name.replace("_", "-")
+    scaffold_project(root, args.kind, name, args.version)
+    print(f"initialized {args.kind} project at {root.resolve()}")
+    return 0
+
+
+def _cmd_install(args: argparse.Namespace) -> int:
+    record = install_source(
+        args.source,
+        namespace=args.namespace,
+        version=args.version,
+        link_mode=args.link_mode,
+        registry_root_override=args.registry_root,
+        cache_root_override=args.cache_root,
+        force=args.force,
+    )
+    print(f"installed {record.package} {record.version} -> {record.installed_root}")
+    return 0
+
+
+def _cmd_update(args: argparse.Namespace) -> int:
+    records = update_installation(
+        args.target,
+        namespace=args.namespace,
+        version=args.version,
+        link_mode=args.link_mode,
+        registry_root_override=args.registry_root,
+        cache_root_override=args.cache_root,
+    )
+    for record in records:
+        print(f"updated {record.package} {record.version} -> {record.installed_root}")
+    return 0
+
+
+def _cmd_remove(args: argparse.Namespace) -> int:
+    removed = remove_installation(
+        args.target,
+        namespace=args.namespace,
+        version=args.version,
+        registry_root_override=args.registry_root,
+    )
+    for path in removed:
+        print(f"removed {path}")
+    return 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    items = list_installed_packages(args.registry_root)
+    if args.json:
+        print(json.dumps(items, indent=2, sort_keys=True))
+        return 0
+    for item in items:
+        print(
+            f'{item["namespace"]}/{item["package"]}/{item["version"]} '
+            f'[{item["link_mode"]}] <- {item["source"]}'
+        )
+    return 0
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    status = installation_status(
+        args.target,
+        namespace=args.namespace,
+        version=args.version,
+        registry_root_override=args.registry_root,
+    )
+    for key in sorted(status):
+        print(f"{key}: {status[key]}")
+    return 0

typst_forge-0.1.0/src/typst_forge/config.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def default_registry_root() -> Path:
+    xdg_data_home = os.environ.get("XDG_DATA_HOME")
+    if xdg_data_home:
+        return Path(xdg_data_home).expanduser() / "typst" / "packages"
+    return Path.home() / ".local" / "share" / "typst" / "packages"
+
+
+def default_cache_root() -> Path:
+    xdg_cache_home = os.environ.get("XDG_CACHE_HOME")
+    if xdg_cache_home:
+        return Path(xdg_cache_home).expanduser() / "typst-forge"
+    return Path.home() / ".cache" / "typst-forge"
+
+
+def registry_root(override: str | None = None) -> Path:
+    if override:
+        return Path(override).expanduser()
+    return default_registry_root()
+
+
+def metadata_root(override: str | None = None) -> Path:
+    return registry_root(override) / ".forge"
+
+
+def cache_root(override: str | None = None) -> Path:
+    if override:
+        return Path(override).expanduser()
+    return default_cache_root()

typst_forge-0.1.0/src/typst_forge/git.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+VERSION_TAG = re.compile(r"^v?(?P<version>\d+(?:\.\d+){1,2}(?:-[0-9A-Za-z.-]+)?)$")
+
+
+@dataclass(frozen=True)
+class GitState:
+    root: Path
+    commit: str | None
+    tags: tuple[str, ...]
+
+
+def run_git(args: list[str], cwd: Path | None = None) -> str:
+    result = subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        check=True,
+        text=True,
+        capture_output=True,
+    )
+    return result.stdout.strip()
+
+
+def git_available() -> bool:
+    return shutil.which("git") is not None
+
+
+def repo_root(start: Path) -> Path:
+    output = run_git(["rev-parse", "--show-toplevel"], cwd=start)
+    return Path(output)
+
+
+def git_state(project_root: Path) -> GitState:
+    root = repo_root(project_root)
+    try:
+        commit = run_git(["rev-parse", "HEAD"], cwd=root)
+    except subprocess.CalledProcessError:
+        commit = None
+    tags_output = ""
+    if commit is not None:
+        tags_output = run_git(["tag", "--points-at", "HEAD"], cwd=root)
+    tags = tuple(sorted(filter(None, tags_output.splitlines())))
+    return GitState(root=root, commit=commit, tags=tags)
+
+
+def normalize_version(tag: str) -> str:
+    match = VERSION_TAG.fullmatch(tag)
+    if not match:
+        raise ValueError(f"tag {tag!r} is not a version-like tag")
+    return match.group("version")
+
+
+def version_key(version: str) -> tuple[object, ...]:
+    normalized = normalize_version(version)
+    core, *suffix = normalized.split("-", 1)
+    parts = tuple(int(part) for part in core.split("."))
+    prerelease = suffix[0] if suffix else ""
+    return (*parts, 1 if not prerelease else 0, prerelease)
+
+
+def highest_version(tags: list[str]) -> str | None:
+    normalized = []
+    for tag in tags:
+        try:
+            normalized.append((version_key(tag), normalize_version(tag)))
+        except ValueError:
+            continue
+    if not normalized:
+        return None
+    return max(normalized, key=lambda item: item[0])[1]
+
+
+def local_version(project_root: Path, requested: str | None = None) -> str:
+    manifest_version = None
+    if requested is not None:
+        return normalize_version(requested)
+
+    try:
+        state = git_state(project_root)
+    except subprocess.CalledProcessError:
+        state = GitState(root=project_root, commit=None, tags=())
+
+    resolved = highest_version(list(state.tags))
+    if resolved is not None:
+        return resolved
+
+    from .manifest import load_manifest
+
+    manifest_version = load_manifest(project_root).version
+    return normalize_version(manifest_version)
+
+
+def remote_tags(remote_url: str) -> list[str]:
+    try:
+        output = run_git(["ls-remote", "--tags", "--refs", remote_url])
+    except subprocess.CalledProcessError as exc:
+        raise ValueError(f"failed to inspect remote tags for {remote_url!r}") from exc
+    tags: list[str] = []
+    for line in output.splitlines():
+        _, ref = line.split("\t", 1)
+        if ref.startswith("refs/tags/"):
+            tags.append(ref.removeprefix("refs/tags/"))
+    return tags
+
+
+def remote_version(remote_url: str, requested: str | None = None) -> str:
+    if requested is not None:
+        return normalize_version(requested)
+    tag = highest_version(remote_tags(remote_url))
+    if tag is None:
+        raise ValueError(f"no version-like tags found for {remote_url!r}")
+    return tag
+
+
+def clone_release(remote_url: str, ref: str, destination: Path) -> Path:
+    if destination.exists():
+        shutil.rmtree(destination)
+    subprocess.run(
+        ["git", "clone", "--quiet", "--depth", "1", "--branch", ref, remote_url, str(destination)],
+        check=True,
+        text=True,
+        capture_output=True,
+    )
+    return destination

typst_forge-0.1.0/src/typst_forge/manifest.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from .git import normalize_version
+
+
+@dataclass(frozen=True)
+class ProjectManifest:
+    name: str
+    version: str
+    entrypoint: str
+    kind: str
+    raw: dict[str, object]
+
+
+def load_manifest(project_root: Path) -> ProjectManifest:
+    path = project_root / "typst.toml"
+    if not path.is_file():
+        raise FileNotFoundError(f"missing manifest: {path}")
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    package = data.get("package")
+    if not isinstance(package, dict):
+        raise ValueError("typst.toml is missing a [package] table")
+
+    name = _require_string(package, "name")
+    version = normalize_version(_require_string(package, "version"))
+    entrypoint = _require_string(package, "entrypoint", default="src/lib.typ")
+
+    tool = data.get("tool")
+    kind = "package"
+    if isinstance(tool, dict):
+        forge = tool.get("typst_forge")
+        if isinstance(forge, dict):
+            maybe_kind = forge.get("kind", "package")
+            if isinstance(maybe_kind, str) and maybe_kind:
+                kind = maybe_kind
+    if entrypoint.startswith("template/"):
+        kind = "template"
+
+    return ProjectManifest(name=name, version=version, entrypoint=entrypoint, kind=kind, raw=data)
+
+
+def _require_string(values: dict[str, object], key: str, default: str | None = None) -> str:
+    value = values.get(key, default)
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"typst.toml [{key}] must be a non-empty string")
+    return value

typst_forge-0.1.0/src/typst_forge/registry.py

@@ -0,0 +1,427 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .config import cache_root, metadata_root, registry_root
+from .git import clone_release, local_version, remote_version
+from .manifest import ProjectManifest, load_manifest
+from .source import SourceSpec, parse_source, source_label
+
+
+@dataclass(frozen=True)
+class InstallRecord:
+    namespace: str
+    package: str
+    version: str
+    source_raw: str
+    source_kind: str
+    source_location: str
+    link_mode: str
+    installed_root: str
+    installed_at: str
+
+    @property
+    def install_path(self) -> Path:
+        return Path(self.installed_root)
+
+
+def package_registry_path(root: str | None, namespace: str, package_name: str, version: str) -> Path:
+    return registry_root(root) / namespace / package_name / version
+
+
+def metadata_path(root: str | None, namespace: str, package_name: str, version: str) -> Path:
+    return metadata_root(root) / namespace / package_name / f"{version}.json"
+
+
+def install_source(
+    source: str | Path,
+    namespace: str = "local",
+    version: str | None = None,
+    link_mode: str = "auto",
+    registry_root_override: str | None = None,
+    cache_root_override: str | None = None,
+    force: bool = False,
+) -> InstallRecord:
+    spec = _normalize_source(source)
+    source_id = source_label(spec)
+    install_root, manifest, resolved_version, source_location = _resolve_source(
+        spec,
+        requested_version=version,
+        cache_root_override=cache_root_override,
+    )
+    target = package_registry_path(registry_root_override, namespace, manifest.name, resolved_version)
+    _install_tree(install_root, target, link_mode=link_mode, force=force)
+    record = InstallRecord(
+        namespace=namespace,
+        package=manifest.name,
+        version=resolved_version,
+        source_raw=source_id,
+        source_kind=spec.kind,
+        source_location=source_location,
+        link_mode=link_mode,
+        installed_root=str(target),
+        installed_at=datetime.now(timezone.utc).isoformat(),
+    )
+    _write_record(record, registry_root_override)
+    return record
+
+
+def update_installation(
+    target: str | Path,
+    namespace: str = "local",
+    version: str | None = None,
+    link_mode: str | None = None,
+    registry_root_override: str | None = None,
+    cache_root_override: str | None = None,
+) -> list[InstallRecord]:
+    records = resolve_records(target, namespace=namespace, version=version, registry_root_override=registry_root_override)
+    updated: list[InstallRecord] = []
+    for record in records:
+        source = _source_from_record(record)
+        updated.append(
+            install_source(
+                source,
+                namespace=record.namespace,
+                version=record.version,
+                link_mode=link_mode or record.link_mode,
+                registry_root_override=registry_root_override,
+                cache_root_override=cache_root_override,
+                force=True,
+            )
+        )
+    return updated
+
+
+def remove_installation(
+    target: str | Path,
+    namespace: str = "local",
+    version: str | None = None,
+    registry_root_override: str | None = None,
+) -> list[Path]:
+    removed: list[Path] = []
+    for record in resolve_records(target, namespace=namespace, version=version, registry_root_override=registry_root_override):
+        install_path = record.install_path
+        if install_path.is_symlink() or install_path.is_file():
+            install_path.unlink()
+        elif install_path.exists():
+            shutil.rmtree(install_path)
+        _remove_record(record, registry_root_override)
+        _prune_empty_dirs(install_path.parent)
+        removed.append(install_path)
+    return removed
+
+
+def list_installed_packages(registry_root_override: str | None = None) -> list[dict[str, str]]:
+    records = _load_records(registry_root_override)
+    if not records:
+        records = _scan_registry(registry_root_override)
+    return [
+        {
+            "namespace": record.namespace,
+            "package": record.package,
+            "version": record.version,
+            "source": record.source_raw,
+            "source_kind": record.source_kind,
+            "link_mode": record.link_mode,
+            "target": record.installed_root,
+        }
+        for record in sorted(records, key=lambda item: (item.namespace, item.package, item.version))
+    ]
+
+
+def installation_status(
+    target: str | Path,
+    namespace: str = "local",
+    version: str | None = None,
+    registry_root_override: str | None = None,
+) -> dict[str, str]:
+    records = resolve_records(target, namespace=namespace, version=version, registry_root_override=registry_root_override)
+    if not records:
+        return {"installed": "no"}
+    if len(records) == 1:
+        record = records[0]
+        return {
+            "installed": "yes",
+            "namespace": record.namespace,
+            "package": record.package,
+            "version": record.version,
+            "source": record.source_raw,
+            "source_kind": record.source_kind,
+            "link_mode": record.link_mode,
+            "target": record.installed_root,
+        }
+    return {
+        "installed": "yes",
+        "count": str(len(records)),
+        "packages": ",".join(f"{record.package}:{record.version}" for record in records),
+    }
+
+
+def resolve_records(
+    target: str | Path,
+    namespace: str = "local",
+    version: str | None = None,
+    registry_root_override: str | None = None,
+) -> list[InstallRecord]:
+    try:
+        spec = _normalize_source(target)
+    except (ValueError, TypeError):
+        spec = None
+
+    records = _load_records(registry_root_override)
+    if spec is not None:
+        source_id = source_label(spec)
+        matching = [record for record in records if record.source_raw == source_id]
+        if version is not None:
+            matching = [record for record in matching if record.version == version]
+        return matching
+
+    package_name = str(target)
+    matching = [record for record in records if record.namespace == namespace and record.package == package_name]
+    if version is not None:
+        matching = [record for record in matching if record.version == version]
+    if matching:
+        return matching
+
+    package_dir = registry_root(registry_root_override) / namespace / package_name
+    if package_dir.exists():
+        if version is not None:
+            child = package_dir / version
+            if child.exists() or child.is_symlink():
+                return [_record_from_path(child, namespace, package_name)]
+        else:
+            return [_record_from_path(child, namespace, package_name) for child in package_dir.iterdir() if child.name and not child.name.startswith(".")]
+    return []
+
+
+def _normalize_source(source: str | Path) -> SourceSpec:
+    if isinstance(source, Path):
+        return parse_source(str(source))
+    return parse_source(str(source))
+
+
+def _resolve_source(
+    spec: SourceSpec,
+    requested_version: str | None,
+    cache_root_override: str | None,
+) -> tuple[Path, ProjectManifest, str, str]:
+    if spec.kind == "local":
+        if spec.path is None:
+            raise ValueError("local source is missing a path")
+        manifest = load_manifest(spec.path)
+        resolved_version = local_version(spec.path, requested_version)
+        if requested_version is not None and manifest.version != resolved_version:
+            raise ValueError(
+                f"manifest version {manifest.version!r} does not match requested version {resolved_version!r}"
+            )
+        if manifest.version != resolved_version:
+            raise ValueError(
+                f"manifest version {manifest.version!r} does not match resolved version {resolved_version!r}"
+            )
+        return spec.path, manifest, resolved_version, str(spec.path)
+
+    if spec.kind == "github":
+        remote_url = _github_url(spec)
+        release = _resolve_remote_release(remote_url, spec.ref or requested_version)
+        checkout = _checkout_cache_path(cache_root_override, spec, release.version)
+        clone_release(remote_url, release.ref, checkout)
+        manifest = load_manifest(checkout)
+        if manifest.version != release.version:
+            raise ValueError(
+                f"manifest version {manifest.version!r} does not match release {release.version!r}"
+            )
+        return checkout, manifest, release.version, remote_url
+
+    if spec.kind == "remote":
+        if spec.url is None:
+            raise ValueError("remote source is missing a url")
+        release = _resolve_remote_release(spec.url, requested_version)
+        checkout = _checkout_cache_path(cache_root_override, spec, release.version)
+        clone_release(spec.url, release.ref, checkout)
+        manifest = load_manifest(checkout)
+        if manifest.version != release.version:
+            raise ValueError(
+                f"manifest version {manifest.version!r} does not match release {release.version!r}"
+            )
+        return checkout, manifest, release.version, spec.url
+
+    raise ValueError(f"unsupported source kind: {spec.kind}")
+
+
+@dataclass(frozen=True)
+class _RemoteRelease:
+    ref: str
+    version: str
+
+
+def _resolve_remote_release(remote_url: str, requested_version: str | None) -> _RemoteRelease:
+    version = remote_version(remote_url, requested_version)
+    return _RemoteRelease(ref=_version_ref(remote_url, version), version=version)
+
+
+def _version_ref(remote_url: str, version: str) -> str:
+    tags = _remote_tag_map(remote_url)
+    if version in tags:
+        return tags[version]
+    prefixed = f"v{version}"
+    if prefixed in tags:
+        return tags[prefixed]
+    raise ValueError(f"version {version!r} is not available on {remote_url!r}")
+
+
+def _remote_tag_map(remote_url: str) -> dict[str, str]:
+    from .git import remote_tags
+
+    tags = remote_tags(remote_url)
+    mapping: dict[str, str] = {}
+    for tag in tags:
+        try:
+            mapping.setdefault(tag, tag)
+            mapping.setdefault(tag.removeprefix("v"), tag)
+        except Exception:
+            continue
+    return mapping
+
+
+def _github_url(spec: SourceSpec) -> str:
+    if not spec.owner or not spec.repo:
+        raise ValueError("github source is missing owner or repo")
+    return f"https://github.com/{spec.owner}/{spec.repo}.git"
+
+
+def _checkout_cache_path(cache_root_override: str | None, spec: SourceSpec, version: str) -> Path:
+    root = cache_root(cache_root_override) / "checkouts"
+    source_id = spec.owner or spec.url or spec.raw
+    safe = source_id.replace(":", "_").replace("/", "_")
+    return root / safe / version
+
+
+def _install_tree(source_root: Path, target: Path, link_mode: str, force: bool) -> None:
+    if target.exists() or target.is_symlink():
+        if not force:
+            if target.is_symlink() and target.resolve(strict=False) == source_root.resolve(strict=False):
+                return
+            raise FileExistsError(f"registry entry already exists: {target}")
+        if target.is_symlink() or target.is_file():
+            target.unlink()
+        else:
+            shutil.rmtree(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if link_mode == "symlink":
+        target.symlink_to(source_root, target_is_directory=True)
+        return
+    if link_mode == "copy":
+        shutil.copytree(source_root, target, symlinks=True, ignore=_copy_ignore)
+        return
+    try:
+        target.symlink_to(source_root, target_is_directory=True)
+    except OSError:
+        shutil.copytree(source_root, target, symlinks=True, ignore=_copy_ignore)
+
+
+def _copy_ignore(_: str, names: list[str]) -> set[str]:
+    ignored = {".git", "__pycache__", ".typst-forge"}
+    return {name for name in names if name in ignored}
+
+
+def _write_record(record: InstallRecord, registry_root_override: str | None) -> None:
+    path = metadata_path(registry_root_override, record.namespace, record.package, record.version)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = asdict(record)
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _remove_record(record: InstallRecord, registry_root_override: str | None) -> None:
+    path = metadata_path(registry_root_override, record.namespace, record.package, record.version)
+    if path.exists():
+        path.unlink()
+        _prune_metadata_dirs(path.parent)
+
+
+def _load_records(registry_root_override: str | None) -> list[InstallRecord]:
+    root = metadata_root(registry_root_override)
+    if not root.exists():
+        return []
+    records: list[InstallRecord] = []
+    for meta in root.rglob("*.json"):
+        try:
+            payload = json.loads(meta.read_text(encoding="utf-8"))
+            records.append(InstallRecord(**payload))
+        except Exception:
+            continue
+    return records
+
+
+def _scan_registry(registry_root_override: str | None) -> list[InstallRecord]:
+    root = registry_root(registry_root_override)
+    if not root.exists():
+        return []
+    records: list[InstallRecord] = []
+    for namespace_dir in root.iterdir():
+        if not namespace_dir.is_dir() or namespace_dir.name.startswith("."):
+            continue
+        for package_dir in namespace_dir.iterdir():
+            if not package_dir.is_dir() or package_dir.name.startswith("."):
+                continue
+            for version_dir in package_dir.iterdir():
+                if version_dir.name.startswith("."):
+                    continue
+                records.append(_record_from_path(version_dir, namespace_dir.name, package_dir.name))
+    return records
+
+
+def _record_from_path(path: Path, namespace: str, package: str) -> InstallRecord:
+    if path.is_symlink():
+        source_location = str(path.resolve(strict=False))
+        source_kind = "local"
+    else:
+        source_location = str(path)
+        source_kind = "copy"
+    return InstallRecord(
+        namespace=namespace,
+        package=package,
+        version=path.name,
+        source_raw=source_location,
+        source_kind=source_kind,
+        source_location=source_location,
+        link_mode="copy" if source_kind == "copy" else "symlink",
+        installed_root=str(path),
+        installed_at="",
+    )
+
+
+def _source_from_record(record: InstallRecord) -> str | Path:
+    if record.source_kind == "local":
+        return Path(record.source_location)
+    if record.source_kind in {"github", "remote"}:
+        return record.source_raw
+    return record.source_location
+
+
+def _prune_empty_dirs(path: Path) -> None:
+    current = path
+    while True:
+        if current.name in {"packages", ".forge"}:
+            break
+        try:
+            current.rmdir()
+        except OSError:
+            break
+        current = current.parent
+
+
+def _prune_metadata_dirs(path: Path) -> None:
+    current = path
+    while True:
+        if current.name == ".forge":
+            break
+        try:
+            current.rmdir()
+        except OSError:
+            break
+        current = current.parent

typst_forge-0.1.0/src/typst_forge/scaffold.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from .git import git_available
+
+
+def scaffold_project(root: Path, kind: str, name: str, version: str) -> None:
+    root = root.resolve()
+    root.mkdir(parents=True, exist_ok=True)
+
+    (root / "src").mkdir(exist_ok=True)
+    if kind == "template":
+        (root / "template").mkdir(exist_ok=True)
+
+    (root / "typst.toml").write_text(_typst_toml(kind, name, version), encoding="utf-8")
+    (root / "src" / "lib.typ").write_text(_lib_typ(kind), encoding="utf-8")
+    if kind == "template":
+        (root / "template" / "main.typ").write_text(_template_main_typ(), encoding="utf-8")
+
+    (root / ".gitignore").write_text(
+        "\n".join(
+            [
+                ".typst-forge",
+                "build",
+                "__pycache__",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    if not git_available():
+        raise RuntimeError("git is required to initialize Typst Forge projects")
+    subprocess.run(["git", "init"], cwd=root, check=True, text=True, capture_output=True)
+
+
+def _typst_toml(kind: str, name: str, version: str) -> str:
+    entrypoint = "template/main.typ" if kind == "template" else "src/lib.typ"
+    return "\n".join(
+        [
+            "[package]",
+            f'name = "{name}"',
+            f'version = "{version}"',
+            f'entrypoint = "{entrypoint}"',
+            "",
+            "[tool.typst_forge]",
+            f'kind = "{kind}"',
+            "",
+        ]
+    )
+
+
+def _lib_typ(kind: str) -> str:
+    if kind == "template":
+        return (
+            "#let render(title, body) = [\n"
+            "= #title\n\n"
+            "#body\n"
+            "]\n"
+        )
+    return '#let hello(name) = "Hello, " + name\n'
+
+
+def _template_main_typ() -> str:
+    return (
+        '#import "../src/lib.typ": render\n\n'
+        '#render("Typst Forge", "template scaffold")\n'
+    )

typst_forge-0.1.0/src/typst_forge/source.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlparse
+
+
+@dataclass(frozen=True)
+class SourceSpec:
+    raw: str
+    kind: str
+    path: Path | None = None
+    url: str | None = None
+    owner: str | None = None
+    repo: str | None = None
+    ref: str | None = None
+
+
+def parse_source(raw: str, cwd: Path | None = None) -> SourceSpec:
+    if not raw:
+        raise ValueError("source cannot be empty")
+
+    cwd = cwd or Path.cwd()
+    candidate = Path(raw).expanduser()
+    if candidate.exists():
+        return SourceSpec(raw=raw, kind="local", path=candidate.resolve())
+
+    if raw.startswith("github:"):
+        return _parse_github(raw[len("github:") :], raw)
+
+    parsed = urlparse(raw)
+    if parsed.scheme:
+        if parsed.scheme in {"http", "https", "ssh", "git", "file"}:
+            return SourceSpec(raw=raw, kind="remote", url=raw)
+        raise ValueError(f"unsupported source url scheme: {parsed.scheme}")
+
+    if raw.startswith("git@") or raw.endswith(".git"):
+        return SourceSpec(raw=raw, kind="remote", url=raw)
+
+    if "/" in raw:
+        return _parse_github(raw, raw)
+
+    maybe_path = (cwd / raw).expanduser()
+    if maybe_path.exists():
+        return SourceSpec(raw=raw, kind="local", path=maybe_path.resolve())
+
+    raise ValueError(f"cannot parse source: {raw!r}")
+
+
+def _parse_github(value: str, raw: str) -> SourceSpec:
+    ref: str | None = None
+    repo_part = value
+    if "@" in value:
+        repo_part, ref = value.rsplit("@", 1)
+    if repo_part.startswith("https://github.com/"):
+        repo_part = repo_part.removeprefix("https://github.com/")
+    if repo_part.startswith("http://github.com/"):
+        repo_part = repo_part.removeprefix("http://github.com/")
+    if repo_part.endswith(".git"):
+        repo_part = repo_part[:-4]
+    owner, _, repo = repo_part.partition("/")
+    if not owner or not repo:
+        raise ValueError(f"invalid github source: {raw!r}")
+    return SourceSpec(raw=raw, kind="github", owner=owner, repo=repo, ref=ref)
+
+
+def source_label(spec: SourceSpec) -> str:
+    if spec.kind == "local" and spec.path is not None:
+        return str(spec.path)
+    if spec.kind == "github" and spec.owner and spec.repo:
+        label = f"github:{spec.owner}/{spec.repo}"
+        if spec.ref:
+            label += f"@{spec.ref}"
+        return label
+    if spec.url:
+        return spec.url
+    return spec.raw

typst_forge-0.1.0/src/typst_forge.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: typst-forge
+Version: 0.1.0
+Summary: A local manager for Typst templates and packages
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Typst Forge
+
+Typst Forge is a small local manager for Typst packages and templates.
+
+It can:
+
+- scaffold a new Typst repo with `git`, `typst.toml`, `src`, and `template/` when needed
+- install local development repos into Typst's package directory
+- install release repos from GitHub or any git URL
+- manage installed packages/templates with versioned registry entries
+- fall back between symlink and copy modes for platform-friendly installs
+
+## Install
+
+This repo is meant to be run with `uv`:
+
+```bash
+uv run typst-forge --help
+```
+
+To run it without installing from a checkout, use `uvx`:
+
+```bash
+uvx --from . typst-forge --help
+```
+
+You can also install directly from GitHub:
+
+```bash
+uvx --from git+https://github.com/<owner>/typst-forge typst-forge --help
+```
+
+## Commands
+
+```bash
+typst-forge init ./my-template --kind template --name my-template --version 0.1.0
+typst-forge init ./my-package --kind package --name my-package --version 0.1.0
+typst-forge install ./my-package --link-mode copy
+typst-forge install github:owner/repo@v1.2.3
+typst-forge list
+typst-forge status my-package
+typst-forge update my-package
+typst-forge remove my-package
+```
+
+## Versioning
+
+- local repos use the `typst.toml` package version unless a matching git tag is present at `HEAD`
+- GitHub and other git URLs install from release tags
+- tags can be written as `v1.2.3` or `1.2.3`; the stored Typst version is normalized to `1.2.3`
+- installed entries live under `~/.local/share/typst/packages/<namespace>/<package>/<version>`
+
+## Tests
+
+Run the in-repo test suite with:
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+## Publishing
+
+The GitHub Actions workflow in [.github/workflows/publish.yml](./.github/workflows/publish.yml)
+publishes tagged releases to PyPI with trusted publishing.
+
+Create and push a version tag like `v0.1.0` to trigger it.

typst_forge-0.1.0/src/typst_forge.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+src/typst_forge/__init__.py
+src/typst_forge/__main__.py
+src/typst_forge/cli.py
+src/typst_forge/config.py
+src/typst_forge/git.py
+src/typst_forge/manifest.py
+src/typst_forge/registry.py
+src/typst_forge/scaffold.py
+src/typst_forge/source.py
+src/typst_forge.egg-info/PKG-INFO
+src/typst_forge.egg-info/SOURCES.txt
+src/typst_forge.egg-info/dependency_links.txt
+src/typst_forge.egg-info/entry_points.txt
+src/typst_forge.egg-info/top_level.txt
+tests/test_cli.py

typst_forge-0.1.0/src/typst_forge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

typst_forge-0.1.0/src/typst_forge.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+typst-forge = typst_forge.cli:main

typst_forge-0.1.0/src/typst_forge.egg-info/top_level.txt

@@ -0,0 +1 @@
+typst_forge

typst_forge-0.1.0/tests/test_cli.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def git(*args: str, cwd: Path) -> None:
+    subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True, text=True)
+
+
+def forge(*args: str, home: Path, capture_output: bool = False) -> subprocess.CompletedProcess[str]:
+    env = os.environ.copy()
+    env["HOME"] = str(home)
+    env["XDG_DATA_HOME"] = str(home / ".local" / "share")
+    env["XDG_CACHE_HOME"] = str(home / ".cache")
+    env["PYTHONPATH"] = str(ROOT / "src")
+    kwargs: dict[str, object] = {"cwd": ROOT, "check": True, "text": True, "env": env}
+    if capture_output:
+        kwargs["capture_output"] = True
+    return subprocess.run(["python3", "-m", "typst_forge", *args], **kwargs)
+
+
+def init_repo(root: Path, kind: str, name: str, version: str) -> Path:
+    forge("init", str(root), "--kind", kind, "--name", name, "--version", version, home=root.parent)
+    git("config", "user.email", "test@example.com", cwd=root)
+    git("config", "user.name", "Test User", cwd=root)
+    git("add", ".", cwd=root)
+    git("commit", "-m", "initial", cwd=root)
+    git("tag", f"v{version}", cwd=root)
+    return root
+
+
+class TypstForgeCliTest(unittest.TestCase):
+    def test_init_creates_expected_layouts(self) -> None:
+        with tempfile.TemporaryDirectory() as tempdir:
+            temp = Path(tempdir)
+            package_repo = temp / "dummy-package"
+            template_repo = temp / "dummy-template"
+
+            init_repo(package_repo, "package", "dummy-package", "0.2.0")
+            init_repo(template_repo, "template", "dummy-template", "0.1.0")
+
+            self.assertTrue((package_repo / "typst.toml").is_file())
+            self.assertTrue((package_repo / "src" / "lib.typ").is_file())
+            self.assertFalse((package_repo / "template").exists())
+
+            self.assertTrue((template_repo / "typst.toml").is_file())
+            self.assertTrue((template_repo / "src" / "lib.typ").is_file())
+            self.assertTrue((template_repo / "template" / "main.typ").is_file())
+
+    def test_local_install_update_list_and_remove(self) -> None:
+        with tempfile.TemporaryDirectory() as tempdir:
+            temp = Path(tempdir)
+            home = temp / "home"
+            home.mkdir()
+            repo = init_repo(temp / "dummy-package", "package", "dummy-package", "0.2.0")
+            install_path = home / ".local" / "share" / "typst" / "packages" / "local" / "dummy-package" / "0.2.0"
+
+            forge("install", str(repo), "--link-mode", "copy", home=home)
+            self.assertTrue(install_path.exists())
+            self.assertTrue((install_path / "src" / "lib.typ").is_file())
+
+            repo.joinpath("src", "lib.typ").write_text('#let hello(name) = "Hi, " + name\n', encoding="utf-8")
+            git("add", "src/lib.typ", cwd=repo)
+            git("commit", "-m", "update lib", cwd=repo)
+
+            forge("update", "dummy-package", home=home)
+            self.assertIn("Hi,", (install_path / "src" / "lib.typ").read_text(encoding="utf-8"))
+
+            list_output = forge("list", home=home, capture_output=True).stdout
+            self.assertIn("local/dummy-package/0.2.0", list_output)
+            self.assertIn("[copy]", list_output)
+
+            status_output = forge("status", "dummy-package", home=home, capture_output=True).stdout
+            self.assertIn("installed: yes", status_output)
+            self.assertIn("package: dummy-package", status_output)
+            self.assertIn("version: 0.2.0", status_output)
+
+            forge("remove", "dummy-package", home=home)
+            self.assertFalse(install_path.exists())
+
+    def test_remote_install_from_git_url_uses_release_tag(self) -> None:
+        with tempfile.TemporaryDirectory() as tempdir:
+            temp = Path(tempdir)
+            home = temp / "home"
+            home.mkdir()
+            repo = init_repo(temp / "remote-template", "template", "remote-template", "1.0.0")
+            remote = temp / "remote-template.git"
+            subprocess.run(["git", "clone", "--bare", str(repo), str(remote)], check=True, capture_output=True, text=True)
+
+            forge("install", f"file://{remote}", "--link-mode", "symlink", home=home)
+            install_path = home / ".local" / "share" / "typst" / "packages" / "local" / "remote-template" / "1.0.0"
+            self.assertTrue(install_path.is_symlink())
+            self.assertIn("remote-template", forge("list", home=home, capture_output=True).stdout)
+
+            status_output = forge("status", f"file://{remote}", home=home, capture_output=True).stdout
+            self.assertIn("source_kind: remote", status_output)
+            self.assertIn("version: 1.0.0", status_output)
+
+    def test_github_style_source_parser_accepts_tagged_refs(self) -> None:
+        from typst_forge.source import parse_source
+
+        spec = parse_source("github:example/hello-world@v1.2.3")
+        self.assertEqual(spec.kind, "github")
+        self.assertEqual(spec.owner, "example")
+        self.assertEqual(spec.repo, "hello-world")
+        self.assertEqual(spec.ref, "v1.2.3")
+
+
+if __name__ == "__main__":
+    unittest.main()