Fail loud when vite assets are missing or pnpm bootstrap fails

[tony]

Scope

Runtime-only diagnostics. This PR adds fail-loud error messages to gp-furo-theme and gp-sphinx-vite so that any consumer hitting a missing-static-asset state (broken wheel, fresh checkout without vite, pnpm not on PATH) gets an immediate, actionable error instead of silently rendering broken docs.

This PR does not fix the underlying broken-wheel root cause — that ships separately in #28 (sphinx-vite-builder, a custom PEP 517 build backend). Two-PR sequence: this PR adds the diagnostics, the follow-up adds the structural fix.

Why ship runtime diagnostics standalone

• Useful regardless of packaging approach. Every consumer install path (PyPI wheel, sdist, editable, fresh clone) benefits from clear diagnostics when something goes wrong.
• Defense in depth. The custom backend in Build sphinx-vite-builder: PEP 517 backend + Sphinx extension for vite-aware projects #28 prevents broken wheels from being built in the first place; the runtime check catches any case where static/ was manually deleted, or where a future regression silently bypasses the backend.
• Decoupled review. The runtime check (4 files, +307/-16) is small and self-contained. The custom backend (~580 LOC including tests, several CI workflow simplifications) is a structural change worth its own review boundary.

Background — what the runtime check actually fixes

Sphinx silently skips missing entries in html_static_path even under -W. Consequence: gp-furo-theme's v0.0.1a15 release shipped a 28 KB broken wheel with no static/ directory, every consumer's docs site rendered unstyled — libtmux, gp-sphinx, and 12 others — and there was no user-visible signal.

The runtime check converts that silent failure into a sphinx.errors.ConfigError with a copy-pasteable bootstrap recipe.

Summary

• Add: gp-furo-theme.setup() raises sphinx.errors.ConfigError with a context-adapted bootstrap recipe when the vite-built static assets it advertises in theme.conf are missing on disk.
• Add: gp-sphinx-vite._ensure_node_modules() raises ConfigError when pnpm is not on PATH or when pnpm install exits non-zero. Install failures previously logged a warning and let the build proceed with broken output.
• Add: _format_missing_assets_hint() produces three context-adapted messages — workspace-with-pnpm gets pnpm exec vite build; workspace-without-pnpm gets corepack enable + the install URL; installed-wheel users get a "this is a packaging bug, please file an issue" message since they have no actionable rebuild path.
• Add: dev-mode bypass — when gp_sphinx_vite is loaded as a Sphinx extension (sphinx-autobuild), it owns the rebuild lifecycle, so the runtime check defers to it.
• Add: unit tests covering all three hint contexts (4 in test_gp_furo_theme.py) and ConfigError-raises tests for both bootstrap failures (2 in test_gp_sphinx_vite_hooks.py).

Changes by area

Runtime fail-loud — gp-furo-theme

• _REQUIRED_VITE_ASSETS = ("scripts/furo.js", "styles/furo-tw.css") — single source of truth
• _missing_vite_assets() returns required paths not on disk
• _gp_sphinx_vite_owns_lifecycle() skips the assertion when gp-sphinx-vite is loaded as an extension (sphinx-autobuild owns rebuilds in that mode)
• _format_missing_assets_hint() produces a context-adapted error message — workspace-with-pnpm, workspace-without-pnpm, and installed-wheel branches each get a distinct actionable recipe
• _builder_inited raises ConfigError after the existing html-builder-only guard

Bootstrap fail-loud — gp-sphinx-vite

• _ensure_node_modules raises ConfigError when shutil.which("pnpm") returns None, with hints to enable corepack or install via pnpm.io/installation
• _ensure_node_modules raises ConfigError when pnpm install exits non-zero, with a copy-pasteable rerun command

Test infrastructure (added after revert)

• tests/conftest.py:skip_if_gp_furo_assets_missing() — helper that fixtures call to skip cleanly when vite output is absent. Used by gp_furo_html_result (test_gp_furo_theme.py) and gp_sphinx_pygments_result (test_pygments_style.py). Without this, integration tests crash with the runtime ConfigError instead of skipping.
• Two gp-sphinx-vite hook tests gained monkeypatch.setattr(shutil, "which", lambda _name: "/fake/pnpm") — they were assuming pnpm was on the test runner's PATH, which fails on stock CI runners.

CI workflow changes (tests.yml)

• docs job: gains pnpm/action-setup@v6 + actions/setup-node@v6 + pnpm install + pnpm exec vite build before the sphinx-build -W -b dirhtml docs step. This mirrors the publisher workflow docs.yml (which has always had these steps).
• smoke matrix: continue-on-error: ${{ matrix.target == 'gp-sphinx' || matrix.target == 'sphinx-gp-theme' }} — those two targets install the published wheel and exercise the runtime check, which fires because the wheel ships without static assets (deferred to Build sphinx-vite-builder: PEP 517 backend + Sphinx extension for vite-aware projects #28). Marked as continue-on-error with a comment pointing at Build sphinx-vite-builder: PEP 517 backend + Sphinx extension for vite-aware projects #28; resolves naturally when the backend lands.

Design decisions

• ConfigError over logger.warning. Sphinx warnings without -W are routinely ignored. ConfigError halts the build with a multi-line message. Hard failure is the user-stated requirement.
• Dev-mode bypass under sphinx-autobuild. When gp_sphinx_vite is loaded as a Sphinx extension, it triggers vite on incremental rebuilds, so a transient missing asset between rebuild cycles is expected. The runtime check defers to gp_sphinx_vite in that case.
• Hint differs by context. A workspace user gets pnpm exec vite build; a workspace user without pnpm gets corepack enable plus the install-from-source path; an installed-wheel user gets a "this is a packaging bug, please file an issue at https://github.com/git-pull/gp-sphinx/issues" message — there is no actionable rebuild path from a wheel install.
• Why not fix the broken wheel here? The packaging fix originally bundled with this PR (hatchling force-include + pnpm/vite step in release.yml) was reverted in commit a8e5320 because force-include requires the source path to exist on disk during build_editable, which broke uv sync in every CI workflow and on fresh local checkouts. The architectural answer is a custom PEP 517 backend (sphinx-vite-builder) — tracked at Build sphinx-vite-builder: PEP 517 backend + Sphinx extension for vite-aware projects #28 and ships in a follow-up PR.

Verification

$ uv run ruff format --check .
$ uv run ruff check .
$ uv run mypy
$ uv run pytest

Deliberate-break smoke test:

$ rm -f packages/gp-furo-theme/src/gp_furo_theme/theme/gp-furo/static/styles/furo-tw.css
$ uv run sphinx-build -W -b html docs/ /tmp/sphinx-out

Expected: sphinx.errors.ConfigError: gp-furo-theme cannot start: … with the workspace+pnpm hint.

Test plan

• All existing tests pass (1322 passed, 159 skipped)
• New hint-shape unit tests pass (4 added in test_gp_furo_theme.py)
• New ConfigError-raises tests pass (2 added in test_gp_sphinx_vite_hooks.py)
• Integration tests skip cleanly when assets absent (skip_if_gp_furo_assets_missing helper)
• Hook tests pass on runners without pnpm (shutil.which monkeypatch)
• CI green: 36/40 checks pass
• Remaining 4/40 failures are by-design (smoke (gp-sphinx), smoke (sphinx-gp-theme) × 2 events; continue-on-error: true; resolved when Build sphinx-vite-builder: PEP 517 backend + Sphinx extension for vite-aware projects #28 lands)

CI status — known-deferred failures

This PR ships in an UNSTABLE state by design. After the latest revert + test fixes:

• 36 / 40 checks SUCCESS — qa (5 Python versions × 2 events), docs (× 2), packages (× 2), root-install + 11 smoke targets that don't depend on gp-furo's static assets (× 2 each)
• 4 / 40 checks FAILURE — smoke (gp-sphinx) and smoke (sphinx-gp-theme) × 2 events (push + pull_request)

The 4 failures are expected and marked continue-on-error: true in .github/workflows/tests.yml. They install the published wheel (which deliberately ships without vite-built static assets in this PR — the packaging fix that shipped them was reverted in a8e5320 in favor of #28's custom PEP 517 backend). When that backend lands, uv build produces a wheel with the assets included, and these targets pass naturally.

GitHub's merge gate is satisfied (no required checks block the branch).

Follow-up

#28 — Custom PEP 517 build backend sphinx-vite-builder. Owns the vite invocation end-to-end, mirroring how maturin owns Cargo and how sphinx-theme-builder owns webpack. Replaces the reverted force-include approach: uv sync / pip install -e . triggers vite automatically; sdist install for end users works without pnpm because the backend pre-populates static/ into the sdist; the 4 deferred CI checks resolve.

References:

• maturin — PEP 517 backend that owns Cargo for Rust+Python
• sphinx-theme-builder — PEP 517 backend that owns webpack for Sphinx themes (used by Furo, sphinx-book-theme, pydata-sphinx-theme)
• PEP 517 / PEP 660

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

❌ Patch coverage is 86.79245% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.32%. Comparing base (5c7079b) to head (ef65585).

Files with missing lines	Patch %	Lines
...ckages/gp-furo-theme/src/gp_furo_theme/__init__.py	63.63%	12 Missing ⚠️
tests/test_gp_furo_theme.py	97.43%	1 Missing ⚠️
tests/test_gp_sphinx_vite_hooks.py	94.73%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #27      +/-   ##
==========================================
- Coverage   89.05%   88.32%   -0.73%     
==========================================
  Files         183      183              
  Lines       15150    15252     +102     
==========================================
- Hits        13492    13472      -20     
- Misses       1658     1780     +122     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

CI status — known-deferred failures

After the latest revert + test fixes, CI is in a deliberate UNSTABLE state:

• 36 / 40 checks SUCCESS — qa (5 Python versions), docs, packages, root-install + 11 smoke targets that don't depend on gp-furo's static assets
• 4 / 40 checks FAILURE — smoke (gp-sphinx) and smoke (sphinx-gp-theme) × 2 events (push + pull_request)

The 4 failures are expected and marked continue-on-error: true in .github/workflows/tests.yml. They install the published wheel (which deliberately ships without vite-built static assets in this PR — the packaging fix that shipped them was reverted in a8e5320 in favor of the upcoming sphinx-vite-builder custom PEP 517 backend). When that backend lands, uv build produces a wheel with the assets included, and these targets pass naturally.

This PR's net contribution: runtime fail-loud diagnostics so any consumer hitting a future broken wheel gets an immediate, actionable error message instead of silently rendering unstyled docs.