paperkit 0.1.0__py3-none-any.whl

paperkit/config.py

@@ -0,0 +1,437 @@
+# Copyright (C) 2026 Vrije Universiteit Brussel. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""Load and validate .paperkit.toml configuration."""
+
+import datetime as dt
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from paperkit import reproducible
+
+
+@dataclass
+class BibtexTidyConfig:
+    enabled: bool = True
+    version: str = "1.14.0"
+    # Sort entries by key and fields within entries. False keeps the file's
+    # own order, for both `paperkit bibtidy` and the tidiness check.
+    sort: bool = True
+
+
+@dataclass
+class UnusedBibConfig:
+    enabled: bool = True
+    # Keys never reported as unused (e.g. an entry staged to be cited later).
+    ignore: list[str] = field(default_factory=list)
+    # When another target sharing a bib file has no up-to-date .aux, run one
+    # draft LaTeX pass (no PDF) to learn its citations. When false, entries
+    # its citations could cover are reported as "not checked", never unused.
+    draft_pass: bool = True
+
+
+@dataclass
+class ChecksConfig:
+    non_ascii: bool = True
+    trailing_whitespace: bool = True
+    final_newline: bool = True
+    unused_bib: UnusedBibConfig = field(default_factory=UnusedBibConfig)
+    font_embedding: bool = True
+    # Part of the font_embedding check: warn on Type 3 (bitmap) fonts.
+    no_type3: bool = True
+    overfull_boxes: bool = True
+    bibtex_tidy: BibtexTidyConfig = field(default_factory=BibtexTidyConfig)
+
+
+@dataclass
+class PageLimitsConfig:
+    # Hard caps. None = no limit (informational only).
+    total: int | None = None
+    # Max pages the content before the section may occupy. A section starting
+    # mid-page counts that page against the budget.
+    before_refs: int | None = None
+    before_ack: int | None = None
+    # False (default): references and acknowledgments are both exempt, so the
+    # budget ends at whichever comes first. True: only the references are
+    # exempt, as at venues that count acknowledgments as text.
+    ack_counts_as_content: bool = False
+    # Regex patterns used to spot the section in the .aux TOC entries.
+    refs_pattern: str = r"(?i)\b(references|bibliography)\b"
+    ack_pattern: str = r"(?i)acknowledg"
+
+
+@dataclass
+class TexliveConfig:
+    # "distro": the base image's texlive-* packages. "upstream": install-tl
+    # from a tlnet repository (see paperkit.texlive for URL resolution).
+    source: str = "distro"
+    # Repository selection, highest precedence first: repository > snapshot
+    # (YYYY-MM-DD, dated tlnet archive) > year (frozen tlnet-final of a
+    # closed release) > live CTAN mirror (not reproducible).
+    repository: str | None = None
+    snapshot: str | None = None
+    year: int | None = None
+    # Expected sha512 of the repository's tlpkg/texlive.tlpdb, checked before
+    # installing so a changed repository fails the image build.
+    tlpdb_sha512: str | None = None
+    scheme: str = "small"
+    collections: list[str] = field(default_factory=list)
+    # Individual packages installed with tlmgr after install-tl.
+    packages: list[str] = field(default_factory=list)
+    docs: bool = False
+    sources: bool = False
+
+
+@dataclass
+class ZipConfig:
+    name: str = ""
+    include: list[str] = field(default_factory=list)
+    # Add each included main's compiled bibliography (<main>.bbl, from the
+    # build directory) next to its .tex. Publishers that compile without
+    # running BibTeX need it; Springer's LNCS checklist asks for it.
+    include_bbl: bool = False
+    exclude: list[str] = field(
+        default_factory=lambda: ["*.aux", "*.log", "*.out", "*.blg", "*.bbl"],
+    )
+
+
+@dataclass
+class PaperkitConfig:
+    # [project]
+    # main is kept as a convenience for the single-target case and always
+    # equals mains[0]. mains is the canonical list the build/check loops over.
+    main: str = "main"
+    mains: list[str] = field(default_factory=list)
+    content_dirs: list[str] = field(default_factory=lambda: ["content"])
+    bib: str = ""
+
+    # [build]
+    engine: str = "pdflatex"
+    passes: int = 3
+    shell_escape: bool = True
+    bibtex: bool = True
+    biber: bool = False
+    output_dir: str = "out"
+    # None = use cpu_count. A positive int caps parallel workers; useful when
+    # one main includes the PDF output of another (`\includepdf`) and needs
+    # to build after it.
+    jobs: int | None = None
+    # Timestamp every tool builds with, for byte-identical rebuilds: an
+    # epoch, an ISO date, or "git" (HEAD's committer date).
+    source_date_epoch: int | str = "git"
+
+    # [docker]
+    base_image: str = "ubuntu:26.04"
+    image_name: str = "paperkit-builder"
+    extra_packages: list[str] = field(default_factory=list)
+    debconf_selections: list[str] = field(default_factory=list)
+
+    # [texlive]
+    texlive: TexliveConfig = field(default_factory=TexliveConfig)
+
+    # [checks]
+    checks: ChecksConfig = field(default_factory=ChecksConfig)
+
+    # [page_limits]
+    page_limits: PageLimitsConfig = field(default_factory=PageLimitsConfig)
+
+    # [zip]
+    zip: ZipConfig = field(default_factory=ZipConfig)
+
+    # [profile]
+    profile_name: str = "acm"
+
+    # resolved root directory (where .paperkit.toml lives)
+    root: Path = field(default_factory=lambda: Path.cwd())
+
+
+TEXLIVE_SCHEMES = (
+    "basic",
+    "context",
+    "full",
+    "gust",
+    "infraonly",
+    "medium",
+    "minimal",
+    "small",
+    "tetex",
+)
+
+# Debian's texlive-* package names differ from TeX Live collection names.
+_DEBIAN_COLLECTION_NAMES = {"science": "mathscience"}
+
+# Names end up in a shell command and an install-tl profile, so keep them to
+# the character set CTAN package names actually use.
+_TL_NAME_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*")
+_SHA512_RE = re.compile(r"[0-9a-f]{128}")
+
+
+def _strip_prefix(name: str, prefix: str) -> str:
+    return name[len(prefix) :] if name.startswith(prefix) else name
+
+
+def _str_list(section: str, key: str, value: object) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(x, str) for x in value):
+        raise ValueError(f"[{section}] {key}: expected a list of strings")
+    return value
+
+
+def parse_texlive(raw: dict[str, object]) -> TexliveConfig:
+    """Build a TexliveConfig from the [texlive] table, rejecting bad values early."""
+    tl = TexliveConfig()
+    known = set(TexliveConfig.__dataclass_fields__)
+    unknown = sorted(set(raw) - known)
+    if unknown:
+        raise ValueError(
+            f"[texlive] unknown key(s): {', '.join(unknown)} "
+            f"(expected: {', '.join(sorted(known))})",
+        )
+
+    source = raw.get("source", tl.source)
+    if not isinstance(source, str) or source not in ("distro", "upstream"):
+        raise ValueError(f'[texlive] source: expected "distro" or "upstream", got {source!r}')
+    tl.source = source
+
+    if "snapshot" in raw and "year" in raw:
+        raise ValueError("[texlive] snapshot and year are mutually exclusive; set only one")
+
+    if "snapshot" in raw:
+        snapshot = raw["snapshot"]
+        # A bare TOML date (snapshot = 2026-09-18) parses as datetime.date.
+        if isinstance(snapshot, dt.date) and not isinstance(snapshot, dt.datetime):
+            snapshot = snapshot.isoformat()
+        if not isinstance(snapshot, str) or not re.fullmatch(r"\d{4}-\d{2}-\d{2}", snapshot):
+            raise ValueError(f'[texlive] snapshot: expected "YYYY-MM-DD", got {snapshot!r}')
+        try:
+            dt.date.fromisoformat(snapshot)
+        except ValueError:
+            raise ValueError(f"[texlive] snapshot: not a valid date: {snapshot!r}") from None
+        tl.snapshot = snapshot
+
+    if "year" in raw:
+        year = raw["year"]
+        if not isinstance(year, int) or isinstance(year, bool) or year < 2008:
+            raise ValueError(
+                f"[texlive] year: expected a TeX Live release year >= 2008, got {year!r}",
+            )
+        tl.year = year
+
+    if "repository" in raw:
+        repo = raw["repository"]
+        if not isinstance(repo, str) or not re.fullmatch(r"(https?|ftp)://\S+", repo):
+            raise ValueError(
+                f"[texlive] repository: expected an http(s):// or ftp:// URL, got {repo!r}",
+            )
+        tl.repository = repo.rstrip("/")
+
+    if "tlpdb_sha512" in raw:
+        digest = raw["tlpdb_sha512"]
+        if not isinstance(digest, str) or not _SHA512_RE.fullmatch(digest.lower()):
+            raise ValueError("[texlive] tlpdb_sha512: expected 128 hex characters")
+        tl.tlpdb_sha512 = digest.lower()
+
+    if "scheme" in raw:
+        scheme = raw["scheme"]
+        name = _strip_prefix(scheme, "scheme-") if isinstance(scheme, str) else ""
+        if name not in TEXLIVE_SCHEMES:
+            raise ValueError(
+                f"[texlive] scheme: unknown scheme {scheme!r} "
+                f"(expected one of: {', '.join(TEXLIVE_SCHEMES)})",
+            )
+        tl.scheme = name
+
+    for key in ("collections", "packages"):
+        if key not in raw:
+            continue
+        names = _str_list("texlive", key, raw[key])
+        if key == "collections":
+            names = [_strip_prefix(n, "collection-") for n in names]
+            for n in names:
+                hint = _DEBIAN_COLLECTION_NAMES.get(n) or (n.replace("-", "") if "-" in n else None)
+                if hint:
+                    raise ValueError(
+                        f"[texlive] collections: {n!r} looks like a Debian package name; "
+                        f"the TeX Live collection is {hint!r}",
+                    )
+        bad = [n for n in names if not _TL_NAME_RE.fullmatch(n)]
+        if bad:
+            raise ValueError(f"[texlive] {key}: invalid name(s): {', '.join(map(repr, bad))}")
+        setattr(tl, key, names)
+
+    for key in ("docs", "sources"):
+        if key in raw:
+            if not isinstance(raw[key], bool):
+                raise ValueError(f"[texlive] {key}: expected true or false")
+            setattr(tl, key, raw[key])
+
+    return tl
+
+
+def parse_unused_bib(raw: object) -> UnusedBibConfig:
+    """`unused_bib = true|false`, or a `[checks.unused_bib]` table."""
+    ub = UnusedBibConfig()
+    if isinstance(raw, bool):
+        ub.enabled = raw
+        return ub
+    if not isinstance(raw, dict):
+        raise ValueError("[checks] unused_bib: expected true, false or a table")
+    unknown = sorted(set(raw) - set(UnusedBibConfig.__dataclass_fields__))
+    if unknown:
+        raise ValueError(f"[checks.unused_bib] unknown key(s): {', '.join(unknown)}")
+    for key in ("enabled", "draft_pass"):
+        if key in raw:
+            if not isinstance(raw[key], bool):
+                raise ValueError(f"[checks.unused_bib] {key}: expected true or false")
+            setattr(ub, key, raw[key])
+    if "ignore" in raw:
+        ub.ignore = _str_list("checks.unused_bib", "ignore", raw["ignore"])
+    return ub
+
+
+def find_config(start: Path | None = None) -> Path:
+    """Walk up from *start* to find .paperkit.toml."""
+    d = (start or Path.cwd()).resolve()
+    while True:
+        candidate = d / ".paperkit.toml"
+        if candidate.is_file():
+            return candidate
+        parent = d.parent
+        if parent == d:
+            raise FileNotFoundError("No .paperkit.toml found in any parent directory")
+        d = parent
+
+
+def load_config(path: Path | None = None) -> PaperkitConfig:
+    """Load .paperkit.toml and return a PaperkitConfig."""
+    if path is None:
+        path = find_config()
+    raw = tomllib.loads(path.read_text())
+
+    cfg = PaperkitConfig(root=path.parent.resolve())
+
+    # [project]
+    proj = raw.get("project", {})
+    if "content_dirs" in proj:
+        cfg.content_dirs = proj["content_dirs"]
+    if "bib" in proj:
+        cfg.bib = proj["bib"]
+
+    # main / mains: accept either key, each may be a string or a list of strings,
+    # and entries may be globs that match against <root>/<pattern>.tex.
+    raw_patterns: list[str] = []
+    for key in ("main", "mains"):
+        if key not in proj:
+            continue
+        v = proj[key]
+        if isinstance(v, str):
+            raw_patterns.append(v)
+        elif isinstance(v, list) and all(isinstance(x, str) for x in v):
+            raw_patterns.extend(v)
+        else:
+            raise ValueError(f"[project] {key}: expected string or list of strings")
+
+    if not raw_patterns:
+        raw_patterns = ["main"]
+
+    expanded: list[str] = []
+    seen: set[str] = set()
+    for pat in raw_patterns:
+        if any(c in pat for c in "*?["):
+            matches = sorted(p.stem for p in cfg.root.glob(f"{pat}.tex"))
+            if not matches:
+                raise FileNotFoundError(
+                    f"[project] '{pat}' matched no .tex files in {cfg.root}",
+                )
+            for m in matches:
+                if m not in seen:
+                    expanded.append(m)
+                    seen.add(m)
+        elif pat not in seen:
+            expanded.append(pat)
+            seen.add(pat)
+
+    cfg.mains = expanded
+    cfg.main = expanded[0]
+
+    # [build]
+    build = raw.get("build", {})
+    for key in ("engine", "passes", "shell_escape", "bibtex", "biber", "output_dir", "jobs"):
+        if key in build:
+            setattr(cfg, key, build[key])
+    if "source_date_epoch" in build:
+        cfg.source_date_epoch = reproducible.parse_setting(build["source_date_epoch"])
+
+    # [docker]
+    docker = raw.get("docker", {})
+    for key in ("base_image", "image_name", "extra_packages", "debconf_selections"):
+        if key in docker:
+            setattr(cfg, key, docker[key])
+
+    # [texlive]
+    cfg.texlive = parse_texlive(raw.get("texlive", {}))
+
+    # [checks]
+    checks_raw = raw.get("checks", {})
+    checks = ChecksConfig()
+    check_keys = (
+        "non_ascii",
+        "trailing_whitespace",
+        "final_newline",
+        "font_embedding",
+        "no_type3",
+        "overfull_boxes",
+    )
+    for key in check_keys:
+        if key in checks_raw:
+            setattr(checks, key, checks_raw[key])
+    checks.unused_bib = parse_unused_bib(checks_raw.get("unused_bib", True))
+    bt = checks_raw.get("bibtex_tidy", {})
+    if isinstance(bt, dict):
+        if "enabled" in bt:
+            checks.bibtex_tidy.enabled = bt["enabled"]
+        if "version" in bt:
+            checks.bibtex_tidy.version = bt["version"]
+        if "sort" in bt:
+            if not isinstance(bt["sort"], bool):
+                raise ValueError("[checks] bibtex_tidy.sort: expected true or false")
+            checks.bibtex_tidy.sort = bt["sort"]
+    cfg.checks = checks
+
+    # [page_limits]
+    pl_raw = raw.get("page_limits", {})
+    pl = PageLimitsConfig()
+    for key in ("total", "before_refs", "before_ack", "refs_pattern", "ack_pattern"):
+        if key in pl_raw:
+            setattr(pl, key, pl_raw[key])
+    if "ack_counts_as_content" in pl_raw:
+        value = pl_raw["ack_counts_as_content"]
+        if not isinstance(value, bool):
+            raise ValueError("[page_limits] ack_counts_as_content: expected true or false")
+        pl.ack_counts_as_content = value
+    cfg.page_limits = pl
+
+    # [zip]
+    zip_raw = raw.get("zip", {})
+    z = ZipConfig()
+    if "name" in zip_raw:
+        z.name = zip_raw["name"]
+    else:
+        z.name = cfg.main
+    if "include" in zip_raw:
+        z.include = zip_raw["include"]
+    if "exclude" in zip_raw:
+        z.exclude = zip_raw["exclude"]
+    if "include_bbl" in zip_raw:
+        if not isinstance(zip_raw["include_bbl"], bool):
+            raise ValueError("[zip] include_bbl: expected true or false")
+        z.include_bbl = zip_raw["include_bbl"]
+    cfg.zip = z
+
+    # [profile]
+    profile = raw.get("profile", {})
+    if "name" in profile:
+        cfg.profile_name = profile["name"]
+
+    return cfg

paperkit/docker.py

@@ -0,0 +1,265 @@
+# Copyright (C) 2026 Vrije Universiteit Brussel. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""Docker image building and container execution via pythainer."""
+
+import contextlib
+import io
+import os
+import shlex
+import subprocess
+import sys
+import tempfile
+from collections.abc import Generator
+from pathlib import Path
+
+from pythainer.builders import UbuntuDockerBuilder
+from pythainer.runners import ConcreteDockerRunner
+
+from paperkit import __version__, texlive
+from paperkit.config import PaperkitConfig
+
+# Lines of captured build output shown when a quiet image build fails.
+_FAILURE_TAIL_LINES = 30
+_FAILURE_LINE_WIDTH = 200
+
+CONTAINER_WORKDIR = Path("/paper")
+CONTAINER_PAPERKIT = Path("/opt/paperkit")
+
+# Distro TeX packages (for [texlive] source = "distro"), always installed
+# together so that switching engine (pdflatex <-> lualatex) or bibliography
+# backend (bibtex <-> biber) does not require a Docker image rebuild.
+_DISTRO_TEX_PACKAGES = [
+    # TeX Live - all engines and common collections
+    "texlive-latex-recommended",
+    "texlive-latex-extra",
+    "texlive-luatex",
+    "texlive-xetex",
+    "texlive-fonts-recommended",
+    "texlive-fonts-extra",
+    "texlive-bibtex-extra",
+    "texlive-science",
+    "texlive-pictures",
+    "texlive-publishers",
+    "texlive-plain-generic",
+    "texlive-extra-utils",
+    # Bibliography
+    "biber",
+    # minted's highlighter
+    "python3-pygments",
+]
+
+# Tools paperkit itself needs, whatever the TeX Live source.
+_TOOL_PACKAGES = [
+    "python3-pip",
+    "poppler-utils",
+    "npm",
+    "unzip",
+    "pandoc",  # used by text_export to strip LaTeX from \title and \begin{abstract}
+]
+
+# paperkit source root: two levels up from this file (src/paperkit/ -> src/ -> repo root)
+_PAPERKIT_SRC_ROOT = Path(__file__).resolve().parent.parent.parent
+# What `pip install` needs from a source checkout (README and LICENSE are
+# referenced by pyproject.toml). Copying only these keeps .git, .venv and
+# working files out of the image and its layer cache.
+_PAPERKIT_SRC_FILES = ("pyproject.toml", "README.md", "LICENSE", "src")
+
+
+def _is_source_checkout() -> bool:
+    """True when paperkit runs from a source tree rather than an installed wheel."""
+    return all((_PAPERKIT_SRC_ROOT / name).exists() for name in _PAPERKIT_SRC_FILES)
+
+
+@contextlib.contextmanager
+def _quiet_stdout_stderr(verbose: bool) -> Generator[None]:
+    """Suppress both stdout and stderr unless verbose.
+
+    pythainer prints [SHELL] lines to stdout; Docker BuildKit progress goes
+    to stderr via inherited file descriptors in subprocess.check_call.
+    """
+    if verbose:
+        yield
+        return
+
+    # Capture Python-level stdout (pythainer's print() calls)
+    old_stdout = sys.stdout
+    sys.stdout = io.StringIO()
+
+    # Redirect OS-level stderr fd (Docker BuildKit output) to a temp file, so
+    # the tail can be shown if the build fails.
+    saved_stderr_fd = os.dup(2)
+    with tempfile.TemporaryFile() as captured:
+        os.dup2(captured.fileno(), 2)
+        try:
+            yield
+        except BaseException:
+            os.dup2(saved_stderr_fd, 2)
+            captured.seek(0)
+            tail = captured.read().decode(errors="replace").splitlines()[-_FAILURE_TAIL_LINES:]
+            # BuildKit echoes whole RUN commands; cut those so the error stays readable.
+            print("\n".join(line[:_FAILURE_LINE_WIDTH] for line in tail), file=sys.stderr)
+            raise
+        finally:
+            sys.stdout = old_stdout
+            os.dup2(saved_stderr_fd, 2)
+            os.close(saved_stderr_fd)
+
+
+@contextlib.contextmanager
+def _quiet_stdout(verbose: bool) -> Generator[None]:
+    """Suppress only stdout (pythainer's [SHELL] lines) unless verbose."""
+    if verbose:
+        yield
+        return
+
+    old_stdout = sys.stdout
+    sys.stdout = io.StringIO()
+    try:
+        yield
+    finally:
+        sys.stdout = old_stdout
+
+
+def build_image(config: PaperkitConfig, verbose: bool = False) -> str:
+    """Build the Docker image and return its tag."""
+    tl = config.texlive
+    if tl.source == "upstream" and not texlive.is_pinned(tl):
+        print(
+            'warning: [texlive] source = "upstream" without snapshot, year or repository '
+            f"installs from the live CTAN repository ({texlive.LIVE_REPOSITORY}); "
+            'rebuilds will pick up newer packages. Set snapshot = "YYYY-MM-DD" to pin it.',
+            file=sys.stderr,
+        )
+
+    builder = make_builder(config)
+
+    # Suppress both stdout ([SHELL] lines) and stderr (BuildKit progress)
+    try:
+        with _quiet_stdout_stderr(verbose):
+            builder.build()
+    except subprocess.CalledProcessError:
+        print(
+            f"Docker image build failed ({config.image_name}); see output above.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return config.image_name
+
+
+def make_builder(config: PaperkitConfig) -> UbuntuDockerBuilder:
+    """Assemble the image definition (Dockerfile + build context) for *config*."""
+    from paperkit.profiles import get_profile
+
+    profile = get_profile(config)
+    tl = config.texlive
+
+    builder = UbuntuDockerBuilder(
+        tag=config.image_name,
+        ubuntu_base_tag=config.base_image,
+    )
+    builder.space()
+
+    # Run apt-get / dpkg without interactive prompts. Without this, packages
+    # whose postinst scripts call debconf (e.g. ttf-mscorefonts-installer)
+    # try the Dialog/Readline/Teletype frontends and fail in BuildKit because
+    # there's no TTY.
+    builder.env("DEBIAN_FRONTEND", "noninteractive")
+    builder.space()
+
+    if tl.source == "upstream":
+        # Prerequisites and TeX Live get their own layers ahead of the tools,
+        # so the (large) TeX Live layer only rebuilds when [texlive] changes.
+        builder.desc("Install prerequisites for upstream TeX Live")
+        builder.add_packages(texlive.APT_PREREQS)
+        builder.space()
+
+        builder.desc(f"Install TeX Live ({texlive.describe(tl)})")
+        builder.run_multiple(texlive.install_commands(tl))
+        builder.env("PATH", f"{texlive.BIN_DIR}:${{PATH}}")
+        builder.space()
+
+        builder.desc("Install tools and profile packages")
+        builder.add_packages(_TOOL_PACKAGES + profile.docker_packages())
+        builder.space()
+    else:
+        # Base + profile packages in one layer so the cache is shared across
+        # all paperkit projects regardless of their per-project extra_packages.
+        builder.desc("Install TeX Live and dependencies")
+        builder.add_packages(_DISTRO_TEX_PACKAGES + _TOOL_PACKAGES + profile.docker_packages())
+        builder.space()
+
+    # Pre-seed debconf answers (e.g. EULA acceptance) before installing
+    # project extras. Must run before add_packages so the postinst scripts
+    # see the preseeded values.
+    if config.debconf_selections:
+        builder.desc("Pre-seed debconf selections")
+        joined = " && ".join(
+            f"echo {shlex.quote(s)} | debconf-set-selections" for s in config.debconf_selections
+        )
+        builder.run(joined)
+        builder.space()
+
+    # Project-specific extras in a separate layer: only this layer is rebuilt
+    # when extra_packages changes between projects.
+    if config.extra_packages:
+        builder.desc("Install project-specific extra packages")
+        builder.add_packages(config.extra_packages)
+        builder.space()
+
+    # bibtex-tidy
+    if config.checks.bibtex_tidy.enabled:
+        version = config.checks.bibtex_tidy.version
+        builder.desc("Install bibtex-tidy for bib file linting")
+        builder.run(f"npm install -g bibtex-tidy@{version}")
+        builder.space()
+
+    # Copy and install paperkit into the image
+    builder.desc("Install paperkit CLI")
+    if _is_source_checkout():
+        for name in _PAPERKIT_SRC_FILES:
+            builder.copy(source=_PAPERKIT_SRC_ROOT / name, destination=CONTAINER_PAPERKIT / name)
+        builder.run(f"pip install --break-system-packages {CONTAINER_PAPERKIT}")
+    else:
+        # Installed from a package index: install the same version in the image.
+        builder.run(f"pip install --break-system-packages paperkit=={__version__}")
+    builder.space()
+
+    builder.desc("Set working directory")
+    builder.workdir(CONTAINER_WORKDIR)
+    return builder
+
+
+def run_in_docker(
+    config: PaperkitConfig,
+    command: str,
+    interactive: bool = False,
+    verbose: bool = False,
+    env: dict[str, str] | None = None,
+) -> int:
+    """Run a command inside the Docker container. Returns exit code.
+
+    *env* is passed with `docker run --env`. The build timestamp travels this
+    way: the image has no git, so the host resolves it and the inner paperkit
+    picks it up from the environment.
+    """
+    runner = ConcreteDockerRunner(
+        image=config.image_name,
+        name=f"{config.image_name}-run",
+        volumes={
+            str(config.root): str(CONTAINER_WORKDIR),
+        },
+        environment_variables=env or {},
+        workdir=CONTAINER_WORKDIR,
+        tty=True,
+        interactive=interactive,
+    )
+
+    # Only suppress stdout ([SHELL] lines); keep stderr so the container's
+    # actual output (build progress, checks) is visible to the user.
+    try:
+        with _quiet_stdout(verbose):
+            runner.run(commands=[command])
+    except subprocess.CalledProcessError as e:
+        return e.returncode
+    return 0