versite 0.0.1__py3-none-any.whl

versite/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

versite/builders/__init__.py

@@ -0,0 +1 @@
+__all__ = ["command"]

versite/builders/command.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from typing import Any
+
+
+class BuilderError(RuntimeError):
+    pass
+
+
+@dataclass
+class BuildResult:
+    site_dir: str
+    metadata: dict[str, Any]
+
+
+@dataclass
+class CommandBuilder:
+    name: str
+    command: list[str]
+
+    def build(
+        self,
+        *,
+        version: str,
+        output_dir: str,
+        config: dict[str, Any],
+        quiet: bool = False,
+    ) -> BuildResult:
+        variables = {
+            "version": version,
+            "output_dir": output_dir,
+            "source": config.get("source", "."),
+            "config_file": config.get("config_file", "mkdocs.yml"),
+        }
+        rendered = [part.format(**variables) for part in self.command]
+        env = os.environ.copy()
+        env["VERSITE_VERSION"] = version
+        if self.name == "mkdocs":
+            env["MIKE_DOCS_VERSION"] = version
+        kwargs: dict[str, Any] = {"check": True, "env": env}
+        if quiet:
+            kwargs["stdout"] = subprocess.DEVNULL
+            kwargs["stderr"] = subprocess.DEVNULL
+        try:
+            subprocess.run(rendered, **kwargs)
+        except FileNotFoundError as exc:
+            raise BuilderError(
+                f"builder command is unavailable: {rendered[0]}"
+            ) from exc
+        except subprocess.CalledProcessError as exc:
+            raise BuilderError(f"builder command failed with exit code {exc.returncode}") from exc
+        return BuildResult(site_dir=output_dir, metadata={"command": rendered})
+
+
+def load_builder(name: str, config: dict[str, Any]) -> CommandBuilder:
+    try:
+        builder_config = config["builders"][name]
+    except KeyError as exc:
+        raise BuilderError(f"unknown builder: {name}") from exc
+    command = builder_config.get("command")
+    if not command:
+        raise BuilderError(f"builder '{name}' has no command configured")
+    return CommandBuilder(name=name, command=list(command))

versite/cli.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from versite.commands import (
+    VersiteError,
+    alias_version,
+    delete_versions,
+    deploy_version,
+    list_versions,
+    props_version,
+    retitle_version,
+    serve_site,
+    set_default,
+)
+from versite.config import apply_cli_overrides, load_config
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="versite")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    deploy = subparsers.add_parser("deploy")
+    deploy.add_argument("version")
+    deploy.add_argument("aliases", nargs="*")
+    _add_common_options(deploy, include_builder=True)
+    deploy.add_argument("--source")
+    deploy.add_argument("--output-dir")
+    deploy.add_argument("--build-command", nargs=argparse.REMAINDER)
+    deploy.add_argument("-q", "--quiet", action="store_true")
+
+    list_parser = subparsers.add_parser("list")
+    list_parser.add_argument("identifier", nargs="?")
+    _add_common_options(list_parser)
+    list_parser.add_argument("--json", action="store_true")
+
+    delete = subparsers.add_parser("delete")
+    delete.add_argument("identifiers", nargs="*")
+    delete.add_argument("--all", action="store_true")
+    _add_common_options(delete)
+
+    alias = subparsers.add_parser("alias")
+    alias.add_argument("identifier")
+    alias.add_argument("aliases", nargs="*")
+    _add_common_options(alias)
+    alias.add_argument("--alias-type", choices=["redirect", "copy", "symlink"])
+
+    retitle = subparsers.add_parser("retitle")
+    retitle.add_argument("identifier")
+    retitle.add_argument("title")
+    _add_common_options(retitle)
+
+    props = subparsers.add_parser("props")
+    props.add_argument("identifier")
+    props.add_argument("prop", nargs="?")
+    _add_common_options(props)
+    props.add_argument("--json", action="store_true")
+
+    default = subparsers.add_parser("set-default")
+    default.add_argument("identifier")
+    _add_common_options(default)
+
+    serve = subparsers.add_parser("serve")
+    _add_common_options(serve)
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=8000)
+
+    return parser
+
+
+def _add_common_options(parser: argparse.ArgumentParser, include_builder: bool = False) -> None:
+    parser.add_argument("--config-file")
+    if include_builder:
+        parser.add_argument("--builder")
+    parser.add_argument("-r", "--remote")
+    parser.add_argument("-b", "--branch")
+    parser.add_argument("-m", "--message")
+    parser.add_argument("-p", "--push", action="store_true", default=None)
+    parser.add_argument("--allow-empty", action="store_true")
+    parser.add_argument("--deploy-prefix")
+    parser.add_argument("-T", "--template", dest="redirect_template")
+    parser.add_argument("--ignore-remote-status", action="store_true")
+
+
+def _load_runtime_config(args: argparse.Namespace) -> dict:
+    config, _ = load_config(args.config_file)
+    return apply_cli_overrides(
+        config,
+        builder=getattr(args, "builder", None),
+        remote=args.remote,
+        branch=args.branch,
+        message=args.message,
+        push=args.push,
+        deploy_prefix=args.deploy_prefix,
+        alias_type=getattr(args, "alias_type", None),
+        redirect_template=args.redirect_template,
+        ignore_remote_status=args.ignore_remote_status,
+        source=getattr(args, "source", None),
+        output_dir=getattr(args, "output_dir", None),
+        build_command=getattr(args, "build_command", None),
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        config = _load_runtime_config(args)
+        push = config.get("push", False)
+        if args.command == "deploy":
+            return deploy_version(
+                config,
+                args.version,
+                args.aliases,
+                message=args.message,
+                push=push,
+                allow_empty=args.allow_empty,
+                quiet=args.quiet,
+            )
+        if args.command == "list":
+            return list_versions(config, args.identifier, as_json=args.json)
+        if args.command == "delete":
+            return delete_versions(
+                config,
+                args.identifiers,
+                delete_all=args.all,
+                message=args.message,
+                push=push,
+                allow_empty=args.allow_empty,
+            )
+        if args.command == "alias":
+            return alias_version(
+                config,
+                args.identifier,
+                args.aliases,
+                alias_type=args.alias_type or config["alias_type"],
+                message=args.message,
+                push=push,
+                allow_empty=args.allow_empty,
+            )
+        if args.command == "retitle":
+            return retitle_version(
+                config,
+                args.identifier,
+                args.title,
+                message=args.message,
+                push=push,
+                allow_empty=args.allow_empty,
+            )
+        if args.command == "props":
+            return props_version(
+                config,
+                args.identifier,
+                args.prop,
+                message=args.message,
+                push=push,
+                allow_empty=args.allow_empty,
+                as_json=args.json,
+            )
+        if args.command == "set-default":
+            return set_default(
+                config,
+                args.identifier,
+                message=args.message,
+                push=push,
+                allow_empty=args.allow_empty,
+            )
+        if args.command == "serve":
+            return serve_site(config, host=args.host, port=args.port)
+        parser.error(f"unsupported command: {args.command}")
+    except (VersiteError, ValueError, KeyError) as exc:
+        print(f"versite: {exc}", file=sys.stderr)
+        return 1
+    except Exception as exc:  # pragma: no cover
+        print(f"versite: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

versite/commands.py

@@ -0,0 +1,406 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from versite.config import normalize_prefix
+from versite.git_utils import GitError, branch_worktree, commit_all, git_root, push_branch
+from versite.jsonpath import parse_assignment, parse_value
+from versite.redirects import write_redirect
+from versite.serve import serve_directory
+from versite.versions import VersionStore
+
+
+class VersiteError(RuntimeError):
+    pass
+
+
+def _site_root(worktree: Path, deploy_prefix: str) -> Path:
+    prefix = normalize_prefix(deploy_prefix)
+    return worktree / prefix if prefix else worktree
+
+
+def _versions_file(worktree: Path, deploy_prefix: str) -> Path:
+    return _site_root(worktree, deploy_prefix) / "versions.json"
+
+
+def _identifier_path(worktree: Path, deploy_prefix: str, identifier: str) -> Path:
+    if identifier.startswith("/") or ".." in Path(identifier).parts:
+        raise VersiteError(f"unsafe identifier path: {identifier}")
+    return _site_root(worktree, deploy_prefix) / identifier
+
+
+def _print(data: Any, as_json: bool = False) -> None:
+    if as_json:
+        print(json.dumps(data, indent=2, sort_keys=True))
+    elif isinstance(data, (dict, list)):
+        print(json.dumps(data, indent=2, sort_keys=True))
+    else:
+        print(data)
+
+
+def _load_store(worktree: Path, deploy_prefix: str) -> VersionStore:
+    return VersionStore.load(_versions_file(worktree, deploy_prefix))
+
+
+def _save_store(worktree: Path, deploy_prefix: str, store: VersionStore) -> None:
+    site_root = _site_root(worktree, deploy_prefix)
+    site_root.mkdir(parents=True, exist_ok=True)
+    store.save(_versions_file(worktree, deploy_prefix))
+
+
+def _root_redirect_href(identifier: str, deploy_prefix: str) -> str:
+    prefix = normalize_prefix(deploy_prefix)
+    if prefix:
+        return f"./{prefix}/{identifier}/"
+    return f"./{identifier}/"
+
+
+def _alias_redirect_href(alias: str, version: str) -> str:
+    alias_parts = Path(alias).parts
+    upward = "../" * max(len(alias_parts), 1)
+    return f"{upward}{version}/"
+
+
+def _copy_contents(source: Path, destination: Path) -> None:
+    if destination.exists() or destination.is_symlink():
+        if destination.is_dir() and not destination.is_symlink():
+            shutil.rmtree(destination)
+        else:
+            destination.unlink()
+    shutil.copytree(source, destination, symlinks=True)
+
+
+def _write_alias(
+    worktree: Path,
+    deploy_prefix: str,
+    alias: str,
+    version: str,
+    alias_type: str,
+    redirect_template: str | None,
+) -> None:
+    alias_path = _identifier_path(worktree, deploy_prefix, alias)
+    version_path = _identifier_path(worktree, deploy_prefix, version)
+    if alias_path.exists() or alias_path.is_symlink():
+        if alias_path.is_dir() and not alias_path.is_symlink():
+            shutil.rmtree(alias_path)
+        else:
+            alias_path.unlink()
+    if alias_type == "redirect":
+        write_redirect(alias_path / "index.html", _alias_redirect_href(alias, version), redirect_template)
+        return
+    if alias_type == "copy":
+        _copy_contents(version_path, alias_path)
+        return
+    if alias_type == "symlink":
+        alias_path.parent.mkdir(parents=True, exist_ok=True)
+        target = os.path.relpath(version_path, alias_path.parent)
+        os.symlink(target, alias_path)
+        return
+    raise VersiteError(f"unsupported alias type: {alias_type}")
+
+
+def _remove_path(path: Path) -> None:
+    if path.is_symlink() or path.is_file():
+        path.unlink(missing_ok=True)
+    elif path.is_dir():
+        shutil.rmtree(path)
+
+
+def list_versions(config: dict[str, Any], identifier: str | None = None, as_json: bool = False) -> int:
+    repo = git_root()
+    with branch_worktree(
+        repo,
+        config["branch"],
+        remote=config["remote"],
+        ignore_remote_status=config.get("ignore_remote_status", False),
+    ) as worktree:
+        store = _load_store(worktree, config["deploy_prefix"])
+        if identifier is None:
+            _print(store.as_list(), as_json)
+            return 0
+        record = store.get(identifier)
+        _print(
+            {
+                "version": record.version,
+                "title": record.title,
+                "aliases": record.aliases,
+                "properties": record.properties,
+            },
+            as_json,
+        )
+    return 0
+
+
+def delete_versions(
+    config: dict[str, Any],
+    identifiers: list[str],
+    *,
+    delete_all: bool = False,
+    message: str | None = None,
+    push: bool = False,
+    allow_empty: bool = False,
+) -> int:
+    if not identifiers and not delete_all:
+        raise VersiteError("delete requires identifiers or --all")
+    repo = git_root()
+    with branch_worktree(
+        repo,
+        config["branch"],
+        remote=config["remote"],
+        ignore_remote_status=config.get("ignore_remote_status", False),
+    ) as worktree:
+        store = _load_store(worktree, config["deploy_prefix"])
+        if delete_all:
+            targets = [record.version for record in list(store.records)]
+        else:
+            targets = identifiers
+        removed_any = False
+        for identifier in targets:
+            version, aliases = store.delete_identifier(identifier)
+            removed_any = True
+            if version is not None:
+                _remove_path(_identifier_path(worktree, config["deploy_prefix"], version))
+            for alias in aliases:
+                _remove_path(_identifier_path(worktree, config["deploy_prefix"], alias))
+        _save_store(worktree, config["deploy_prefix"], store)
+        committed = commit_all(
+            worktree,
+            message or ("Delete all deployed versions" if delete_all else f"Delete {' '.join(targets)}"),
+            allow_empty=allow_empty,
+        )
+        if push and committed:
+            push_branch(worktree, config["remote"], config["branch"])
+        return 0 if removed_any else 1
+
+
+def alias_version(
+    config: dict[str, Any],
+    identifier: str,
+    aliases: list[str],
+    *,
+    alias_type: str,
+    message: str | None = None,
+    push: bool = False,
+    allow_empty: bool = False,
+) -> int:
+    if not aliases:
+        raise VersiteError("alias requires at least one alias")
+    repo = git_root()
+    with branch_worktree(
+        repo,
+        config["branch"],
+        remote=config["remote"],
+        ignore_remote_status=config.get("ignore_remote_status", False),
+    ) as worktree:
+        store = _load_store(worktree, config["deploy_prefix"])
+        record = store.get(identifier)
+        store.upsert(record.version, aliases=aliases)
+        for alias in aliases:
+            _write_alias(
+                worktree,
+                config["deploy_prefix"],
+                alias,
+                record.version,
+                alias_type,
+                config.get("redirect_template"),
+            )
+        _save_store(worktree, config["deploy_prefix"], store)
+        committed = commit_all(
+            worktree,
+            message or f"Update aliases for {record.version}",
+            allow_empty=allow_empty,
+        )
+        if push and committed:
+            push_branch(worktree, config["remote"], config["branch"])
+    return 0
+
+
+def retitle_version(
+    config: dict[str, Any],
+    identifier: str,
+    title: str,
+    *,
+    message: str | None = None,
+    push: bool = False,
+    allow_empty: bool = False,
+) -> int:
+    repo = git_root()
+    with branch_worktree(
+        repo,
+        config["branch"],
+        remote=config["remote"],
+        ignore_remote_status=config.get("ignore_remote_status", False),
+    ) as worktree:
+        store = _load_store(worktree, config["deploy_prefix"])
+        store.retitle(identifier, title)
+        _save_store(worktree, config["deploy_prefix"], store)
+        committed = commit_all(worktree, message or f"Retitle {identifier}", allow_empty=allow_empty)
+        if push and committed:
+            push_branch(worktree, config["remote"], config["branch"])
+    return 0
+
+
+def props_version(
+    config: dict[str, Any],
+    identifier: str,
+    prop: str | None = None,
+    *,
+    message: str | None = None,
+    push: bool = False,
+    allow_empty: bool = False,
+    as_json: bool = False,
+) -> int:
+    repo = git_root()
+    needs_write = prop is not None and ("=" in prop or prop.endswith("-"))
+    with branch_worktree(
+        repo,
+        config["branch"],
+        remote=config["remote"],
+        ignore_remote_status=config.get("ignore_remote_status", False),
+    ) as worktree:
+        store = _load_store(worktree, config["deploy_prefix"])
+        if prop is None:
+            _print(store.get_properties(identifier), as_json)
+            return 0
+        if "=" in prop:
+            path, raw_value = parse_assignment(prop)
+            props = store.set_property(identifier, path, parse_value(raw_value))
+            _save_store(worktree, config["deploy_prefix"], store)
+            committed = commit_all(
+                worktree,
+                message or f"Update properties for {identifier}",
+                allow_empty=allow_empty,
+            )
+            if push and committed:
+                push_branch(worktree, config["remote"], config["branch"])
+            _print(props, as_json)
+            return 0
+        if prop.endswith("-"):
+            path = prop[:-1]
+            props = store.delete_property(identifier, path)
+            _save_store(worktree, config["deploy_prefix"], store)
+            committed = commit_all(
+                worktree,
+                message or f"Update properties for {identifier}",
+                allow_empty=allow_empty,
+            )
+            if push and committed:
+                push_branch(worktree, config["remote"], config["branch"])
+            _print(props, as_json)
+            return 0
+        _print(store.get_property(identifier, prop), as_json)
+    return 0
+
+
+def set_default(
+    config: dict[str, Any],
+    identifier: str,
+    *,
+    message: str | None = None,
+    push: bool = False,
+    allow_empty: bool = False,
+) -> int:
+    repo = git_root()
+    with branch_worktree(
+        repo,
+        config["branch"],
+        remote=config["remote"],
+        ignore_remote_status=config.get("ignore_remote_status", False),
+    ) as worktree:
+        store = _load_store(worktree, config["deploy_prefix"])
+        store.get(identifier)
+        write_redirect(
+            worktree / "index.html",
+            _root_redirect_href(identifier, config["deploy_prefix"]),
+            config.get("redirect_template"),
+        )
+        committed = commit_all(worktree, message or f"Set default site to {identifier}", allow_empty=allow_empty)
+        if push and committed:
+            push_branch(worktree, config["remote"], config["branch"])
+    return 0
+
+
+def serve_site(config: dict[str, Any], host: str = "127.0.0.1", port: int = 8000) -> int:
+    repo = git_root()
+    with branch_worktree(
+        repo,
+        config["branch"],
+        remote=config["remote"],
+        ignore_remote_status=True,
+    ) as worktree:
+        serve_directory(worktree, host=host, port=port)
+    return 0
+
+
+def deploy_version(
+    config: dict[str, Any],
+    version: str,
+    aliases: list[str],
+    *,
+    message: str | None = None,
+    push: bool = False,
+    allow_empty: bool = False,
+    quiet: bool = False,
+) -> int:
+    from versite.builders.command import BuilderError, load_builder
+
+    repo = git_root()
+    builder_name = config["builder"]
+    builder = load_builder(builder_name, config)
+    builder_config = config["builders"][builder_name]
+    output_dir = config.get("output_dir")
+    temp_output: tempfile.TemporaryDirectory[str] | None = None
+    if output_dir is None:
+        temp_output = tempfile.TemporaryDirectory(prefix="versite-build-")
+        output_dir = temp_output.name
+    try:
+        builder.build(
+            version=version,
+            output_dir=output_dir,
+            config=builder_config,
+            quiet=quiet,
+        )
+        with branch_worktree(
+            repo,
+            config["branch"],
+            remote=config["remote"],
+            ignore_remote_status=config.get("ignore_remote_status", False),
+        ) as worktree:
+            site_root = _site_root(worktree, config["deploy_prefix"])
+            site_root.mkdir(parents=True, exist_ok=True)
+            version_path = _identifier_path(worktree, config["deploy_prefix"], version)
+            _copy_contents(Path(output_dir), version_path)
+            store = _load_store(worktree, config["deploy_prefix"])
+            title = version
+            existing = store.find(version)
+            if existing is not None:
+                title = existing.title
+            store.upsert(version, title=title, aliases=aliases)
+            for alias in aliases:
+                _write_alias(
+                    worktree,
+                    config["deploy_prefix"],
+                    alias,
+                    version,
+                    config["alias_type"],
+                    config.get("redirect_template"),
+                )
+            _save_store(worktree, config["deploy_prefix"], store)
+            committed = commit_all(
+                worktree,
+                message or f"Deploy {version}",
+                allow_empty=allow_empty,
+            )
+            if push and committed:
+                push_branch(worktree, config["remote"], config["branch"])
+        return 0
+    except BuilderError as exc:
+        raise VersiteError(str(exc)) from exc
+    finally:
+        if temp_output is not None:
+            temp_output.cleanup()