sphinx-vite-builder 0.0.1a16.dev0__py3-none-any.whl

sphinx_vite_builder/__init__.py

@@ -0,0 +1,43 @@
+"""sphinx-vite-builder: PEP 517 backend + Sphinx extension.
+
+Two orthogonal entry points share one subprocess core:
+
+- :mod:`sphinx_vite_builder.build` — the PEP 517 backend module that
+  consumer packages reference via
+  ``[build-system].build-backend = "sphinx_vite_builder.build"``.
+- :func:`sphinx_vite_builder.setup` — the Sphinx extension entry point
+  that ``conf.py`` references via
+  ``extensions = ["sphinx_vite_builder"]``.
+
+Neither head calls the other; they share the implementation modules
+under :mod:`sphinx_vite_builder._internal`.
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+__version__ = "0.0.1a16.dev0"
+
+if t.TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+
+def setup(app: Sphinx) -> dict[str, t.Any]:
+    """Register the Sphinx-extension head.
+
+    Phase 1 ships the PEP 517 backend; the extension head's full
+    implementation (vite watch on ``sphinx-autobuild``, one-shot build
+    on ``sphinx-build``) lands in a follow-up commit. For now this
+    stub registers the extension so consumers can declare it without
+    a no-such-module error, and returns the safety metadata.
+    """
+    del app
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+        "version": __version__,
+    }
+
+
+__all__ = ("__version__", "setup")

sphinx_vite_builder/_internal/__init__.py

@@ -0,0 +1,7 @@
+"""Private implementation modules for ``sphinx-vite-builder``.
+
+Anything imported from this package is *not* part of the stable public
+surface — both heads (PEP 517 backend in :mod:`sphinx_vite_builder.build`
+and Sphinx extension in :mod:`sphinx_vite_builder`) reach in here, but
+external callers should not.
+"""

sphinx_vite_builder/_internal/bus.py

@@ -0,0 +1,191 @@
+"""Thread + asyncio event-loop bridge.
+
+Sphinx's event hooks (``builder-inited``, ``build-finished``, …) are
+synchronous callables. The orchestration logic that they drive is
+asyncio-based (:class:`sphinx_vite_builder._internal.process.AsyncProcess`
+uses ``asyncio.create_subprocess_exec``, pipe drainers, etc.). The bridge
+between them is a *single* event loop running in a single daemon
+thread, kept alive across ``builder-inited`` re-fires for
+``sphinx-autobuild``.
+
+Usage from a Sphinx hook:
+
+.. code-block:: python
+
+    bus = AsyncioBus()
+    bus.start()
+    bus.call_sync(some_coro())
+    # ...
+    bus.stop(timeout=5.0)
+
+The bus has no Sphinx-specific knowledge; tests construct one and drive
+it directly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+import typing as t
+
+if t.TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncioBus:
+    """A single asyncio event loop running in a daemon thread.
+
+    Lifecycle:
+
+    1. :meth:`start` spawns the thread; waits until the loop is ready.
+    2. Hooks run :meth:`call_sync` (block on result) or :meth:`call_soon`
+       (fire-and-forget).
+    3. :meth:`stop` schedules the loop to stop, joins the thread.
+
+    The bus is single-use. After ``stop()`` it is not safe to start
+    again — construct a new instance.
+    """
+
+    def __init__(self, *, name: str = "sphinx-vite-builder-bus") -> None:
+        self._name = name
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._ready = threading.Event()
+        # ``_stopped`` is set once a started bus has actually been torn
+        # down. It enforces the class-level "single-use" contract from
+        # ``start()``; a stop-before-start is a no-op and leaves this
+        # ``False`` (the bus was never really live).
+        self._stopped = False
+
+    @property
+    def is_running(self) -> bool:
+        """True iff the loop thread is alive."""
+        return self._thread is not None and self._thread.is_alive()
+
+    def start(self) -> None:
+        """Start the background event loop.
+
+        Idempotent if the bus is already running; raises
+        :class:`RuntimeError` if the bus has previously been stopped
+        (the class is single-use, per the class docstring).
+        """
+        if self._stopped:
+            msg = "AsyncioBus is single-use; construct a new instance after stop()"
+            raise RuntimeError(msg)
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._ready.clear()
+        self._thread = threading.Thread(
+            target=self._run,
+            daemon=True,
+            name=self._name,
+        )
+        self._thread.start()
+        # Block until the loop has been assigned. Without this, a
+        # call_sync() racing the thread startup would deref None.
+        self._ready.wait()
+
+    def call_sync(
+        self,
+        coro: Coroutine[t.Any, t.Any, t.Any],
+        *,
+        timeout: float | None = None,
+    ) -> t.Any:
+        """Schedule ``coro`` on the loop and block on its result.
+
+        Parameters
+        ----------
+        coro
+            The coroutine object (call-but-don't-await first).
+        timeout
+            Forwarded to ``concurrent.futures.Future.result``. ``None``
+            blocks indefinitely.
+
+        Raises
+        ------
+        RuntimeError
+            If the bus is not running.
+        """
+        if self._loop is None:
+            # Close the coroutine before raising so we don't leak a
+            # "coroutine was never awaited" warning at gc time.
+            coro.close()
+            msg = "AsyncioBus.call_sync() called before start()"
+            raise RuntimeError(msg)
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        return future.result(timeout=timeout)
+
+    def call_soon(
+        self,
+        coro: Coroutine[t.Any, t.Any, t.Any],
+    ) -> None:
+        """Schedule ``coro`` and return immediately. Errors go to the bus logger."""
+        if self._loop is None:
+            coro.close()
+            msg = "AsyncioBus.call_soon() called before start()"
+            raise RuntimeError(msg)
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+
+        def _log_exception(fut: t.Any) -> None:
+            exc = fut.exception()
+            if exc is not None:
+                logger.error(
+                    "background coroutine on %s raised",
+                    self._name,
+                    exc_info=exc,
+                )
+
+        future.add_done_callback(_log_exception)
+
+    def stop(self, *, timeout: float = 5.0) -> None:
+        """Stop the loop and join the thread. Idempotent.
+
+        Once a started bus has been stopped, ``_stopped`` is set so a
+        subsequent ``start()`` on the same instance raises rather than
+        silently re-spawning. A stop-before-start is a no-op and leaves
+        ``_stopped`` unchanged.
+        """
+        if self._loop is None or self._thread is None:
+            return
+        if not self._thread.is_alive():
+            self._thread = None
+            self._loop = None
+            self._stopped = True
+            return
+
+        self._loop.call_soon_threadsafe(self._loop.stop)
+        self._thread.join(timeout=timeout)
+        if self._thread.is_alive():
+            logger.warning(
+                "%s thread did not exit within %.1fs of loop.stop()",
+                self._name,
+                timeout,
+            )
+        self._thread = None
+        self._loop = None
+        self._stopped = True
+
+    def _run(self) -> None:
+        """Thread target: own and run the loop."""
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        self._loop = loop
+        self._ready.set()
+        try:
+            loop.run_forever()
+        finally:
+            try:
+                # Cancel any remaining tasks so they don't leak past
+                # the loop's death.
+                pending = asyncio.all_tasks(loop)
+                for task in pending:
+                    task.cancel()
+                if pending:
+                    loop.run_until_complete(
+                        asyncio.gather(*pending, return_exceptions=True),
+                    )
+            finally:
+                loop.close()

sphinx_vite_builder/_internal/errors.py

@@ -0,0 +1,42 @@
+"""Diagnostic error types raised by the backend and extension.
+
+Each error carries a multi-line, copy-pasteable hint so the failure is
+fixable from the message itself. The PEP 517 backend re-raises these as
+their own type (so build frontends like pip / uv display the full
+message); the Sphinx extension re-wraps them in
+:class:`sphinx.errors.ConfigError` so Sphinx halts the build with the
+same content.
+"""
+
+from __future__ import annotations
+
+
+class SphinxViteBuilderError(Exception):
+    """Base class for all sphinx-vite-builder-raised diagnostic errors."""
+
+
+class PnpmMissingError(SphinxViteBuilderError):
+    """Raised when ``pnpm`` is not on ``PATH``.
+
+    pnpm is not pip-installable, so the backend cannot bootstrap it the
+    way maturin bootstraps Rust via ``puccinialin``. The hint surfaces
+    the canonical install paths (``corepack enable``, the pnpm.io
+    install URL) so the user has an actionable next step.
+    """
+
+
+class NodeModulesInstallError(SphinxViteBuilderError):
+    """Raised when ``pnpm install`` exits non-zero.
+
+    Surfaces the install command that failed and a re-run recipe. Callers
+    should attach the captured stderr to the message before raising so
+    the underlying pnpm diagnostic is visible at the call site.
+    """
+
+
+class ViteFailedError(SphinxViteBuilderError):
+    """Raised when ``pnpm exec vite build`` exits non-zero.
+
+    Surfaces the vite invocation that failed plus context (cwd, exit
+    code). Callers should attach the captured stderr.
+    """

sphinx_vite_builder/_internal/process.py

@@ -0,0 +1,242 @@
+"""Async subprocess wrapper used by the Vite/pnpm orchestration.
+
+Wraps :func:`asyncio.create_subprocess_exec` with the conventions the
+backend and extension heads need:
+
+- ``stdout`` / ``stderr`` are piped through line-buffered drainers that
+  prefix each line with a label and route it to a
+  :class:`logging.Logger` — info for stdout, warning for stderr.
+- ``PYTHONUNBUFFERED=1`` is forced into the child env so Python tools
+  invoked via the package-manager bridge don't withhold their output.
+- On POSIX, the child runs in a new session (``start_new_session=True``)
+  so ``SIGTERM`` cleanly takes down the entire process tree (``pnpm exec``
+  shells out to multiple intermediate processes — without session
+  isolation, only the top-level pnpm wrapper would exit).
+- :meth:`AsyncProcess.terminate` is graceful-then-forceful: SIGTERM,
+  await up to ``timeout`` seconds, escalate to SIGKILL if the child is
+  still alive. Idempotent: calling on an already-exited process is a
+  no-op.
+
+Argument lists are passed directly to the asyncio subprocess primitive;
+no shell, no string interpolation, no command-injection surface.
+
+The class is intentionally generic over "what command to run" so the
+same wrapper covers the production vite / pnpm calls and the fake
+shell scripts used in tests.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+import pathlib
+import sys
+import typing as t
+
+if t.TYPE_CHECKING:
+    pass
+
+_module_logger = logging.getLogger(__name__)
+
+
+class AsyncProcess:
+    """Async wrapper around a subprocess (one-shot or long-running).
+
+    Used for both ``pnpm install`` (one-shot, awaited) and
+    ``pnpm exec vite build --watch`` (long-running, terminated on
+    teardown).
+    """
+
+    def __init__(
+        self,
+        *,
+        label: str = "subprocess",
+        logger: logging.Logger | logging.LoggerAdapter[t.Any] | None = None,
+    ) -> None:
+        # Accepts either a stdlib Logger or a LoggerAdapter (Sphinx's
+        # ``sphinx.util.logging.SphinxLoggerAdapter`` is a LoggerAdapter
+        # subclass). Both expose the .log() method the drainers use.
+        self._label = label
+        self._logger: logging.Logger | logging.LoggerAdapter[t.Any] = (
+            logger if logger is not None else _module_logger
+        )
+        self._process: asyncio.subprocess.Process | None = None
+        self._drainers: list[asyncio.Task[None]] = []
+        self._stderr_buffer: list[str] = []
+
+    @property
+    def is_running(self) -> bool:
+        """True iff the child has been started and has not yet exited."""
+        return self._process is not None and self._process.returncode is None
+
+    @property
+    def returncode(self) -> int | None:
+        """Process exit code, or ``None`` if the child hasn't exited (yet)."""
+        return self._process.returncode if self._process is not None else None
+
+    @property
+    def pid(self) -> int | None:
+        """Child process ID, or ``None`` if not started."""
+        return self._process.pid if self._process is not None else None
+
+    @property
+    def captured_stderr(self) -> str:
+        """Joined stderr lines captured by the drainer.
+
+        Useful for surfacing the underlying tool's diagnostic in error
+        messages when a build fails.
+        """
+        return "\n".join(self._stderr_buffer)
+
+    async def start(
+        self,
+        command: t.Sequence[str],
+        *,
+        cwd: pathlib.Path,
+        env: t.Mapping[str, str] | None = None,
+    ) -> None:
+        """Spawn ``command`` and start draining its stdout / stderr.
+
+        Parameters
+        ----------
+        command
+            Argument list. Passed straight to the asyncio subprocess
+            primitive; no shell.
+        cwd
+            Working directory for the child.
+        env
+            Optional environment override. ``PYTHONUNBUFFERED=1`` is
+            always injected on top of whatever this provides (or, if
+            ``None``, on top of :data:`os.environ`).
+
+        Raises
+        ------
+        RuntimeError
+            If :meth:`start` is called twice on the same instance
+            without an intervening :meth:`terminate`.
+        """
+        if self._process is not None:
+            msg = "AsyncProcess.start() called twice; spawn a new instance instead"
+            raise RuntimeError(msg)
+
+        merged_env = dict(env) if env is not None else dict(os.environ)
+        merged_env["PYTHONUNBUFFERED"] = "1"
+
+        # POSIX-only: ``start_new_session`` puts the child in its own
+        # session/process group so SIGTERM to that group takes down
+        # ``pnpm exec`` plus all its descendants. On Windows there's no
+        # equivalent; the asyncio default is fine.
+        spawn_kwargs: dict[str, t.Any] = {}
+        if sys.platform != "win32":
+            spawn_kwargs["start_new_session"] = True
+
+        self._process = await asyncio.create_subprocess_exec(
+            *command,
+            cwd=str(cwd),
+            env=merged_env,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            **spawn_kwargs,
+        )
+
+        # Pipe drainers — capture-and-log line by line so callers get
+        # immediate visibility into the tool's progress.
+        assert self._process.stdout is not None
+        assert self._process.stderr is not None
+        self._drainers = [
+            asyncio.create_task(
+                self._drain(self._process.stdout, level=logging.INFO),
+                name=f"{self._label}-stdout-drainer",
+            ),
+            asyncio.create_task(
+                self._drain(
+                    self._process.stderr,
+                    level=logging.WARNING,
+                    capture=self._stderr_buffer,
+                ),
+                name=f"{self._label}-stderr-drainer",
+            ),
+        ]
+
+    async def wait(self) -> int:
+        """Wait for the child to exit; return its exit code.
+
+        Drains the stdout / stderr pipes to completion before returning.
+        """
+        if self._process is None:
+            msg = "AsyncProcess.wait() called before start()"
+            raise RuntimeError(msg)
+        returncode = await self._process.wait()
+        # Let the drainers consume any final buffered lines before
+        # returning to the caller.
+        await asyncio.gather(*self._drainers, return_exceptions=True)
+        return returncode
+
+    async def terminate(self, *, timeout: float = 5.0) -> int | None:
+        """Send SIGTERM; escalate to SIGKILL after ``timeout`` seconds.
+
+        Idempotent — calling on an already-exited process is a no-op
+        and returns the existing exit code (or ``None`` if never started).
+
+        Parameters
+        ----------
+        timeout
+            Seconds to wait for graceful exit after SIGTERM.
+
+        Returns
+        -------
+        int | None
+            The child's exit code, or ``None`` if :meth:`start` was
+            never called.
+        """
+        if self._process is None:
+            return None
+        if self._process.returncode is not None:
+            return self._process.returncode
+
+        self._process.terminate()
+        try:
+            await asyncio.wait_for(self._process.wait(), timeout=timeout)
+        except asyncio.TimeoutError:
+            self._logger.warning(
+                "[%s] did not exit within %.1fs of SIGTERM; sending SIGKILL",
+                self._label,
+                timeout,
+            )
+            # ProcessLookupError race: the child can exit between
+            # TimeoutError and kill().
+            with contextlib.suppress(ProcessLookupError):
+                self._process.kill()
+            await self._process.wait()
+
+        # Wait for drainers to consume their last buffered line before
+        # the caller proceeds; surface no exception if a drainer raised.
+        await asyncio.gather(*self._drainers, return_exceptions=True)
+        return self._process.returncode
+
+    async def _drain(
+        self,
+        stream: asyncio.StreamReader,
+        *,
+        level: int,
+        capture: list[str] | None = None,
+    ) -> None:
+        """Consume ``stream`` line by line; log each line.
+
+        Optionally append every (non-empty) line to ``capture`` so callers
+        can surface it in error messages.
+        """
+        while True:
+            try:
+                line = await stream.readline()
+            except (BrokenPipeError, ConnectionResetError):
+                return
+            if not line:
+                return
+            text = line.decode("utf-8", errors="replace").rstrip("\n")
+            if text:
+                self._logger.log(level, "[%s] %s", self._label, text)
+                if capture is not None:
+                    capture.append(text)

sphinx_vite_builder/_internal/vite.py

@@ -0,0 +1,387 @@
+"""Vite + pnpm orchestration: detection, install, one-shot build, watch.
+
+This module is the shared orchestration core consumed by both heads:
+
+- The PEP 517 backend (:mod:`sphinx_vite_builder.build`) calls
+  :func:`run_vite_build` from each of its hooks, before delegating to
+  hatchling.
+- The Sphinx extension (:mod:`sphinx_vite_builder`) calls
+  :func:`run_vite_build` (one-shot) or its watch sibling from
+  ``builder-inited``.
+
+Fast-fail discipline: every prerequisite is checked up front so the
+caller gets an actionable diagnostic instead of a generic spawn-failure
+deep in the asyncio plumbing.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import pathlib
+import shutil
+import textwrap
+import typing as t
+
+from .bus import AsyncioBus
+from .errors import (
+    NodeModulesInstallError,
+    PnpmMissingError,
+    ViteFailedError,
+)
+from .process import AsyncProcess
+
+logger = logging.getLogger(__name__)
+
+
+def pnpm_install_command(*, package_manager: str = "pnpm") -> tuple[str, ...]:
+    """Build the canonical "install workspace deps" argv.
+
+    ``--frozen-lockfile`` matches the workspace's pinned ``pnpm-lock.yaml``;
+    pnpm refuses to mutate the lockfile or auto-resolve unspecified deps,
+    so the install is reproducible across machines and CI.
+
+    Examples
+    --------
+    >>> pnpm_install_command()
+    ('pnpm', 'install', '--frozen-lockfile')
+    >>> pnpm_install_command(package_manager="npm")
+    ('npm', 'install', '--frozen-lockfile')
+    """
+    return (package_manager, "install", "--frozen-lockfile")
+
+
+def vite_build_command(*, package_manager: str = "pnpm") -> tuple[str, ...]:
+    """Build the canonical one-shot "vite build" argv.
+
+    Examples
+    --------
+    >>> vite_build_command()
+    ('pnpm', 'exec', 'vite', 'build')
+    >>> vite_build_command(package_manager="npm")
+    ('npm', 'exec', 'vite', 'build')
+    """
+    return (package_manager, "exec", "vite", "build")
+
+
+def vite_watch_command(*, package_manager: str = "pnpm") -> tuple[str, ...]:
+    """Build the canonical Vite-watch argv.
+
+    Examples
+    --------
+    >>> vite_watch_command()
+    ('pnpm', 'exec', 'vite', 'build', '--watch')
+    >>> vite_watch_command(package_manager="npm")
+    ('npm', 'exec', 'vite', 'build', '--watch')
+    """
+    return (package_manager, "exec", "vite", "build", "--watch")
+
+
+def _detect_ci_provider() -> str | None:
+    """Return a canonical CI-provider name, or ``None`` if not in CI.
+
+    Detection precedence: most-specific provider wins. Each provider's
+    canonical env var (per their docs) is checked first; the generic
+    ``CI=true`` is the fallback for "we know we're in CI but don't
+    recognise the provider".
+
+    Provider env vars (canonical, per upstream docs):
+
+    - GitHub Actions: ``GITHUB_ACTIONS=true``
+    - CircleCI: ``CIRCLECI=true``
+    - Azure Pipelines: ``TF_BUILD=True`` (Team Foundation Build)
+    - GitLab CI: ``GITLAB_CI=true``
+    - Generic: ``CI=true``
+    """
+    env = os.environ
+    # Map of "canonical name" → "env var to check (truthy)". Order
+    # matters: more-specific entries first.
+    providers: tuple[tuple[str, str], ...] = (
+        ("github-actions", "GITHUB_ACTIONS"),
+        ("circleci", "CIRCLECI"),
+        ("azure-pipelines", "TF_BUILD"),
+        ("gitlab", "GITLAB_CI"),
+        ("ci", "CI"),
+    )
+    for name, var in providers:
+        value = env.get(var, "").strip().lower()
+        if value in {"1", "true"}:
+            return name
+    return None
+
+
+# Each per-provider snippet is a *copy-pasteable* config fragment that
+# adds pnpm + Node to the platform's pipeline before the Python build
+# step runs. Versions follow the upstream pnpm CI guide
+# (https://pnpm.io/continuous-integration); update in lockstep with
+# the workspace's pnpm-lock.yaml's `packageManager` if it pins
+# something different.
+_CI_SETUP_RECIPES: dict[str, str] = {
+    "github-actions": textwrap.dedent(
+        """\
+        - uses: pnpm/action-setup@v6
+          with:
+            version: 10
+        - uses: actions/setup-node@v6
+          with:
+            node-version: 22
+            cache: pnpm""",
+    ),
+    "circleci": textwrap.dedent(
+        """\
+        - run:
+            name: Set up pnpm
+            command: |
+              npm install --global corepack@latest
+              corepack enable
+              corepack prepare pnpm@latest-10 --activate""",
+    ),
+    "azure-pipelines": textwrap.dedent(
+        """\
+        - task: NodeTool@0
+          inputs:
+            versionSpec: '22.x'
+          displayName: 'Set up Node'
+        - script: |
+            npm install --global corepack@latest
+            corepack enable
+            corepack prepare pnpm@latest-10 --activate
+          displayName: 'Set up pnpm'""",
+    ),
+    "gitlab": textwrap.dedent(
+        """\
+        before_script:
+          - npm install --global corepack@latest
+          - corepack enable
+          - corepack prepare pnpm@latest-10 --activate""",
+    ),
+    "ci": "  # Use your CI's package-manager setup mechanism to install pnpm",
+}
+
+
+def _format_ci_recipe_block(provider: str | None) -> str:
+    """Return a multi-line CI-specific setup snippet, or an empty string.
+
+    Called by :func:`_format_pnpm_missing_hint` when CI is detected so
+    the user's error message includes a copy-pasteable config fragment
+    for their platform.
+    """
+    if provider is None:
+        return ""
+
+    pretty: dict[str, str] = {
+        "github-actions": "GitHub Actions",
+        "circleci": "CircleCI",
+        "azure-pipelines": "Azure Pipelines",
+        "gitlab": "GitLab CI",
+        "ci": "this CI environment",
+    }
+    label = pretty.get(provider, provider)
+    recipe = _CI_SETUP_RECIPES.get(provider, "")
+    return textwrap.dedent(
+        f"""\
+
+        Detected CI provider: {label}. Add the following to your pipeline
+        config (before the Python build step that triggers this backend):
+
+{textwrap.indent(recipe, "          ")}
+        """,
+    ).rstrip()
+
+
+def _format_pnpm_missing_hint(vite_root: pathlib.Path) -> str:
+    """Multi-line, copy-pasteable hint when pnpm is not on PATH."""
+    ci_recipe = _format_ci_recipe_block(_detect_ci_provider())
+    return (
+        textwrap.dedent(
+            f"""\
+        sphinx-vite-builder: cannot bootstrap the vite toolchain.
+        `pnpm` is not on PATH. Install it via one of:
+
+          corepack enable        # Node 16.10+ ships corepack
+          curl -fsSL https://get.pnpm.io/install.sh | sh -
+
+        See https://pnpm.io/installation
+
+        Then re-run with `pnpm` available, or, if this environment is not
+        supposed to build assets (e.g. a wheel-only install with the
+        static tree pre-baked), set `SPHINX_VITE_BUILDER_SKIP=1`.
+
+        Vite project root resolved to: {vite_root}
+        """,
+        ).rstrip()
+        + ci_recipe
+    )
+
+
+def _format_install_failed_hint(
+    *,
+    vite_root: pathlib.Path,
+    install_cmd: tuple[str, ...],
+    returncode: int,
+    stderr: str,
+) -> str:
+    """Multi-line hint when ``pnpm install`` exits non-zero."""
+    cmd_str = " ".join(install_cmd)
+    stderr_block = stderr.strip() or "(no stderr captured)"
+    return textwrap.dedent(
+        f"""\
+        sphinx-vite-builder: `{cmd_str}` exited with code {returncode} in {vite_root}.
+        The vite-managed theme assets cannot be produced; aborting the
+        build rather than shipping unstyled docs.
+
+        Fix:
+          cd {vite_root}
+          {cmd_str}
+
+        Captured stderr:
+        {textwrap.indent(stderr_block, "  ")}
+        """,
+    ).rstrip()
+
+
+def _format_vite_failed_hint(
+    *,
+    vite_root: pathlib.Path,
+    build_cmd: tuple[str, ...],
+    returncode: int,
+    stderr: str,
+) -> str:
+    """Multi-line hint when ``pnpm exec vite build`` exits non-zero."""
+    cmd_str = " ".join(build_cmd)
+    stderr_block = stderr.strip() or "(no stderr captured)"
+    return textwrap.dedent(
+        f"""\
+        sphinx-vite-builder: `{cmd_str}` exited with code {returncode} in {vite_root}.
+        Vite reported a build error; the resulting wheel/docs would be
+        unstyled. Aborting before any further build steps.
+
+        Captured stderr:
+        {textwrap.indent(stderr_block, "  ")}
+        """,
+    ).rstrip()
+
+
+def _resolve_vite_root(project_root: pathlib.Path) -> pathlib.Path | None:
+    """Locate the Vite project root next to ``project_root``.
+
+    Convention: a sibling ``web/`` directory containing ``package.json``
+    is the Vite project. Returns ``None`` if no such directory exists
+    (e.g. when the build runs inside an unpacked sdist where ``web/``
+    was excluded — in that case the caller should treat the static
+    tree as pre-baked and skip vite).
+    """
+    candidate = project_root / "web"
+    if candidate.is_dir() and (candidate / "package.json").is_file():
+        return candidate
+    return None
+
+
+async def _run_install(
+    vite_root: pathlib.Path,
+    *,
+    install_cmd: tuple[str, ...],
+) -> None:
+    """Run ``pnpm install --frozen-lockfile``; raise on non-zero exit."""
+    proc = AsyncProcess(label="pnpm-install", logger=logger)
+    await proc.start(install_cmd, cwd=vite_root)
+    returncode = await proc.wait()
+    if returncode != 0:
+        raise NodeModulesInstallError(
+            _format_install_failed_hint(
+                vite_root=vite_root,
+                install_cmd=install_cmd,
+                returncode=returncode,
+                stderr=proc.captured_stderr,
+            ),
+        )
+
+
+async def _run_build(
+    vite_root: pathlib.Path,
+    *,
+    build_cmd: tuple[str, ...],
+) -> None:
+    """Run ``pnpm exec vite build``; raise on non-zero exit."""
+    proc = AsyncProcess(label="vite-build", logger=logger)
+    await proc.start(build_cmd, cwd=vite_root)
+    returncode = await proc.wait()
+    if returncode != 0:
+        raise ViteFailedError(
+            _format_vite_failed_hint(
+                vite_root=vite_root,
+                build_cmd=build_cmd,
+                returncode=returncode,
+                stderr=proc.captured_stderr,
+            ),
+        )
+
+
+def run_vite_build(
+    project_root: pathlib.Path | None = None,
+    *,
+    package_manager: str = "pnpm",
+) -> None:
+    """Run a one-shot ``pnpm exec vite build`` in ``<project_root>/web``.
+
+    Short-circuits when:
+
+    - ``SPHINX_VITE_BUILDER_SKIP=1`` is set in the environment (escape
+      hatch for downstream packagers who pre-bake the static tree
+      themselves).
+    - The expected ``web/`` directory is absent — the typical case
+      when building a wheel from an unpacked sdist (where ``web/`` was
+      excluded but ``static/`` was pre-baked into the sdist).
+
+    Otherwise, fast-fails:
+
+    - :class:`PnpmMissingError` if ``pnpm`` is not on ``PATH``.
+    - :class:`NodeModulesInstallError` if ``pnpm install`` exits
+      non-zero.
+    - :class:`ViteFailedError` if ``pnpm exec vite build`` exits
+      non-zero.
+    """
+    if os.environ.get("SPHINX_VITE_BUILDER_SKIP"):
+        logger.info("SPHINX_VITE_BUILDER_SKIP set; skipping vite build")
+        return
+
+    project_root = (project_root or pathlib.Path.cwd()).resolve()
+    vite_root = _resolve_vite_root(project_root)
+    if vite_root is None:
+        logger.info(
+            "no web/ alongside %s; assuming pre-baked static tree (sdist build)",
+            project_root,
+        )
+        return
+
+    if shutil.which(package_manager) is None:
+        raise PnpmMissingError(_format_pnpm_missing_hint(vite_root))
+
+    install_cmd = pnpm_install_command(package_manager=package_manager)
+    build_cmd = vite_build_command(package_manager=package_manager)
+    needs_install = not (vite_root / "node_modules").is_dir()
+
+    bus = AsyncioBus(name="sphinx-vite-builder-build-bus")
+    bus.start()
+    try:
+        if needs_install:
+            logger.info("installing JS deps in %s via %s", vite_root, install_cmd)
+            bus.call_sync(_run_install(vite_root, install_cmd=install_cmd))
+        logger.info("building vite assets in %s", vite_root)
+        bus.call_sync(_run_build(vite_root, build_cmd=build_cmd))
+    finally:
+        bus.stop()
+
+
+__all__: tuple[str, ...] = (
+    "pnpm_install_command",
+    "run_vite_build",
+    "vite_build_command",
+    "vite_watch_command",
+)
+
+
+# Re-exports for type-checker friendliness when consumers import
+# the orchestration module directly.
+_AsyncProcess: t.TypeAlias = AsyncProcess
+_AsyncioBus: t.TypeAlias = AsyncioBus

sphinx_vite_builder/build.py

@@ -0,0 +1,94 @@
+"""PEP 517 / PEP 660 build backend module.
+
+Consumer ``pyproject.toml`` references this module via:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["hatchling>=1.0", "sphinx-vite-builder"]
+    build-backend = "sphinx_vite_builder.build"
+    backend-path = ["../sphinx-vite-builder/src"]    # for in-tree workspace builds
+
+Each PEP 517 hook runs :func:`run_vite_build` to populate the consumer
+package's vite-managed ``static/`` tree, then delegates to
+:mod:`hatchling.build` for the actual sdist / wheel / editable
+construction. The hooks are pure functions, defined at module scope,
+mirroring the canonical layout of `flit_core.buildapi` and
+`hatchling.build`.
+
+Optional hooks (``get_requires_for_build_*`` and
+``prepare_metadata_for_build_*``) are aliased verbatim to hatchling's
+implementations — vite has no influence on dependency resolution or
+distribution metadata, so passing those calls through unmodified is
+both correct and trivially side-effect-free.
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+import hatchling.build as _hatchling
+
+from ._internal.vite import run_vite_build
+
+
+def build_wheel(
+    wheel_directory: str,
+    config_settings: dict[str, t.Any] | None = None,
+    metadata_directory: str | None = None,
+) -> str:
+    """PEP 517 ``build_wheel``: vite-build, then hatchling-pack."""
+    run_vite_build()
+    return _hatchling.build_wheel(wheel_directory, config_settings, metadata_directory)
+
+
+def build_editable(
+    wheel_directory: str,
+    config_settings: dict[str, t.Any] | None = None,
+    metadata_directory: str | None = None,
+) -> str:
+    """PEP 660 ``build_editable``: vite-build, then hatchling-pack-editable."""
+    run_vite_build()
+    return _hatchling.build_editable(
+        wheel_directory, config_settings, metadata_directory
+    )
+
+
+def build_sdist(
+    sdist_directory: str,
+    config_settings: dict[str, t.Any] | None = None,
+) -> str:
+    """PEP 517 ``build_sdist``: pre-bake static so the sdist→wheel chain works.
+
+    Running vite at sdist-build time means the resulting ``.tar.gz``
+    contains a populated ``static/`` tree (even though the source repo
+    gitignores it). Downstream consumers can then ``pip install`` from
+    the sdist without pnpm or Node — the wheel-from-sdist build will
+    skip vite (no ``web/`` in the unpacked tree) and ship the
+    pre-baked assets via hatchling's normal file selection.
+    """
+    run_vite_build()
+    return _hatchling.build_sdist(sdist_directory, config_settings)
+
+
+# The optional hooks have no vite-side concern — pass through verbatim.
+# Keeping them as module-level aliases (rather than wrapping functions)
+# preserves their identity for build frontends that introspect the
+# module surface.
+get_requires_for_build_wheel = _hatchling.get_requires_for_build_wheel
+get_requires_for_build_sdist = _hatchling.get_requires_for_build_sdist
+get_requires_for_build_editable = _hatchling.get_requires_for_build_editable
+prepare_metadata_for_build_wheel = _hatchling.prepare_metadata_for_build_wheel
+prepare_metadata_for_build_editable = _hatchling.prepare_metadata_for_build_editable
+
+
+__all__: tuple[str, ...] = (
+    "build_editable",
+    "build_sdist",
+    "build_wheel",
+    "get_requires_for_build_editable",
+    "get_requires_for_build_sdist",
+    "get_requires_for_build_wheel",
+    "prepare_metadata_for_build_editable",
+    "prepare_metadata_for_build_wheel",
+)

sphinx_vite_builder-0.0.1a16.dev0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: sphinx-vite-builder
+Version: 0.0.1a16.dev0
+Summary: PEP 517 build backend + Sphinx extension that orchestrates Vite via pnpm
+Project-URL: Repository, https://github.com/git-pull/gp-sphinx
+Author-email: Tony Narlock <tony@git-pull.com>
+License: MIT
+Keywords: backend,build,extension,pep517,pnpm,sphinx,vite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Sphinx
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.10
+Requires-Dist: hatchling>=1.0
+Requires-Dist: sphinx>=8.1
+Description-Content-Type: text/markdown
+
+# sphinx-vite-builder
+
+PEP 517 build backend and Sphinx extension that transparently orchestrates
+[Vite](https://vitejs.dev/) builds via [pnpm](https://pnpm.io/) for
+Sphinx-theme packages whose static assets (CSS / JS) are produced by a
+JavaScript toolchain.
+
+## What it solves
+
+A common pattern for modern Sphinx themes is a Python package whose
+`theme/<name>/static/` directory ships built CSS and JS that were
+produced by a JS build tool (Vite, webpack, …). The build artefacts are
+gitignored — they're reproducibly built, not source code. But that
+creates two friction points:
+
+1. **Editable installs and source-tree builds** crash with confusing
+   errors when the static dir is empty (e.g. hatchling's
+   `Forced include not found`).
+2. **CI workflows** must duplicate `pnpm install + vite build` setup
+   steps in every job that touches the package.
+
+`sphinx-vite-builder` owns the Vite invocation end-to-end — exactly the
+way [maturin](https://github.com/PyO3/maturin) owns Cargo for
+Rust+Python packages, or
+[sphinx-theme-builder](https://github.com/pradyunsg/sphinx-theme-builder)
+owns webpack for older Sphinx themes.
+
+## Two heads, one subprocess core
+
+### PEP 517 build backend
+
+Drop-in replacement for `hatchling.build`. Runs `pnpm exec vite build`
+before delegating wheel/sdist construction to hatchling.
+
+```toml
+# packages/your-theme/pyproject.toml
+[build-system]
+requires = ["hatchling>=1.0", "sphinx-vite-builder"]
+build-backend = "sphinx_vite_builder.build"
+backend-path = ["../sphinx-vite-builder/src"]    # for in-tree workspace consumption
+```
+
+The backend short-circuits when `web/` (the Vite source tree) is absent
+— so `pip install <pkg>.tar.gz` from an unpacked sdist works without
+pnpm or Node, because the sdist already contains pre-baked
+`static/`.
+
+### Sphinx extension
+
+Loaded from `conf.py`. Runs Vite as part of the docs lifecycle:
+
+- `sphinx-build` → `pnpm exec vite build` once before the docs build
+- `sphinx-autobuild` → `pnpm exec vite build --watch` as a child process
+  for the lifetime of the autobuild server, with idempotent re-fire on
+  rebuilds and graceful teardown on signal / `atexit`
+
+```python
+# docs/conf.py
+extensions = ["sphinx_vite_builder"]
+sphinx_vite_root = "../packages/your-theme/web"   # path to vite project
+sphinx_vite_mode = "auto"                          # auto | dev | prod | disabled
+```
+
+## Fast-fail diagnostics
+
+When prerequisites are missing the backend / extension raises
+actionable errors rather than producing broken output:
+
+- `PnpmMissingError` — `pnpm` not on `PATH`; hint includes
+  `corepack enable` and the `pnpm.io` install URL
+- `NodeModulesInstallError` — `pnpm install` exited non-zero; hint
+  includes the rerun command
+- `ViteFailedError` — `pnpm exec vite build` exited non-zero; hint
+  surfaces the captured stderr
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sphinx_vite_builder-0.0.1a16.dev0.dist-info/RECORD

@@ -0,0 +1,12 @@
+sphinx_vite_builder/__init__.py,sha256=DRzFcEjIvO6EiVhejmwKIfCkIq0kkWavYsETA35sypM,1310
+sphinx_vite_builder/build.py,sha256=JZdoqFuC7lnm545v83V2PJbhcYTobC_krt0dGIfWUnc,3400
+sphinx_vite_builder/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sphinx_vite_builder/_internal/__init__.py,sha256=LsWjSKGvTuBuvRo5RO6nhKwd3kQCYjYgKQWzbLzHMbM,315
+sphinx_vite_builder/_internal/bus.py,sha256=XXMZzwxkfLXwTElIxObcg-kCllJ9nkACRSs2uSwYWZQ,6356
+sphinx_vite_builder/_internal/errors.py,sha256=28-cqrd-EujwGR5KAv4ivajuf1UsvoXYGT5d7qDY584,1505
+sphinx_vite_builder/_internal/process.py,sha256=xBmC21kL00xta3YYH4OdmKwaWYQClCPyjoqLS7osX8M,8755
+sphinx_vite_builder/_internal/vite.py,sha256=UwAa9vYgV5OH5iQlk6bVdGA7upRY1AOWsiyoGqEPOyI,12369
+sphinx_vite_builder-0.0.1a16.dev0.dist-info/METADATA,sha256=rARfbqBtuiotl7-zOe24tef-k9Of_5yTntqMEvNVT1A,4012
+sphinx_vite_builder-0.0.1a16.dev0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sphinx_vite_builder-0.0.1a16.dev0.dist-info/entry_points.txt,sha256=PD4YaXZpK576ROxF4--oD7eFjjRgUX3Mk_C4B_dXvAU,62
+sphinx_vite_builder-0.0.1a16.dev0.dist-info/RECORD,,

sphinx_vite_builder-0.0.1a16.dev0.dist-info/WHEEL

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

sphinx_vite_builder-0.0.1a16.dev0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[sphinx.extensions]
+sphinx-vite-builder = sphinx_vite_builder