sphinx-vite-builder 0.0.1a16.dev0__tar.gz → 0.0.1a16.dev2__tar.gz

sphinx_vite_builder-0.0.1a16.dev2/AGENTS.md

@@ -0,0 +1,208 @@
+# AGENTS.md — `sphinx-vite-builder`
+
+Guidance for AI agents (Claude Code, Cursor, Copilot, Codex, …) and
+human contributors working on this package. Mirrors the higher-level
+guidance at `gp-sphinx/CLAUDE.md`; `packages/sphinx-vite-builder/CLAUDE.md`
+points here so Claude Code reads the same content as other agent runners.
+
+## What this package is
+
+Two orthogonal entry points sharing one subprocess core:
+
+1. **PEP 517 build backend** at `sphinx_vite_builder.build`. Runs
+   `pnpm exec vite build` before delegating wheel/sdist construction
+   to `hatchling.build`. Consumer packages declare it via
+   `[build-system].build-backend = "sphinx_vite_builder.build"`.
+2. **Sphinx extension** at `sphinx_vite_builder:setup`. Hooks
+   `builder-inited` and `build-finished` so `sphinx-build` /
+   `sphinx-autobuild` automatically run vite — one-shot for prod, a
+   long-lived `vite build --watch` child process for autobuild — with
+   graceful teardown on signal / `atexit`.
+
+Both heads consume the smart-subprocess core under
+`sphinx_vite_builder._internal/`: `process.py` (`AsyncProcess` —
+asyncio subprocess wrapper with POSIX session isolation,
+SIGTERM-then-SIGKILL teardown, line-buffered stdout/stderr drainers,
+captured stderr for error surfacing), `bus.py` (`AsyncioBus` — single
+asyncio loop in a daemon thread for sync↔async bridging),
+`vite.py` (orchestration: detect `web/`, check pnpm via `shutil.which`,
+spawn install/build), and `errors.py` (`PnpmMissingError`,
+`NodeModulesInstallError`, `ViteFailedError`).
+
+**Phase 1 status:** The PEP 517 backend is fully implemented and
+tested. The Sphinx extension `setup()` is a placeholder — it
+registers cleanly in `conf.py` but doesn't yet hook the docs build
+lifecycle. The full extension implementation (event handlers, vite
+watch, teardown) lands in a follow-up release.
+
+## The design contract — keep this invariant
+
+> **Sources should check for node, pnpm, etc and error if it's not
+> good, then build. Wheels should have the build files baked in and
+> not need node and pnpm at all.**
+
+This is the central invariant. When you change anything in the
+backend, vite orchestration, or release pipeline, ask: "does this
+preserve the source-vs-wheel asymmetry?"
+
+### Source builds — fail loud, fail informatively
+
+A consumer building from source (cloned tree, `[tool.uv.sources]` git
+URL, `pip install <repo-path>`) goes through the PEP 517 chain. The
+backend's `build_wheel` / `build_editable` / `build_sdist` hooks
+**MUST** run vite, and vite **MUST** be available. If pnpm or Node is
+missing:
+
+- Raise the typed exception (`PnpmMissingError`,
+  `NodeModulesInstallError`, or `ViteFailedError`) — never a bare
+  `subprocess.CalledProcessError` or `FileNotFoundError`. The typed
+  exception lets consumers `except` cleanly via the
+  `SphinxViteBuilderError` base class.
+- Each error's message MUST be a multi-line, copy-pasteable hint
+  formatted by `_format_*_hint()`. Include the canonical install
+  paths (`corepack enable`, `https://pnpm.io/installation`), the
+  resolved vite-root path, and the `SPHINX_VITE_BUILDER_SKIP=1`
+  escape-hatch line.
+- Detect CI via `_detect_ci_provider()`. When CI is detected, append
+  the platform-specific YAML/config snippet from `_CI_SETUP_RECIPES`
+  so the consumer can copy-paste the fix into their pipeline.
+  Supported providers: GitHub Actions, CircleCI, Azure Pipelines,
+  GitLab CI, plus a generic fallback for `CI=true`.
+
+### Wheel installs — zero toolchain required
+
+A consumer doing `pip install <package>==<version>` from PyPI gets a
+wheel that **already contains** the vite-built `static/` tree
+(populated by the backend at release time, packed via hatchling's
+`artifacts` directive). The PEP 517 chain doesn't run. No backend
+invocation. No `_run_vite_build()`. No `shutil.which("pnpm")`. The
+end user sees Python and only Python.
+
+### Wheel-from-sdist — the bridge case
+
+A consumer doing `pip install <pkg>.tar.gz` (or `--no-binary :all:`)
+runs the wheel-from-sdist chain:
+
+1. pip/uv unpacks the sdist into a temp dir
+2. Calls our backend's `build_wheel` against the unpacked tree
+3. The backend's vite-orchestration sees no `web/` (excluded from
+   sdist via `[tool.hatch.build.targets.sdist] exclude = ["web/"]`)
+   and short-circuits cleanly — `_resolve_vite_root()` returns
+   `None`, vite is never invoked
+4. Hatchling packs the pre-baked `static/` (carried in the sdist via
+   `[tool.hatch.build] artifacts`) into the wheel
+
+Net: **sdist install also requires zero toolchain**. The
+`web/`-absent short-circuit is the load-bearing primitive.
+
+## QA permutations — keep them green
+
+The install-path permutations every change must keep green:
+
+| # | Path | Toolchain | Expected |
+|---|---|---|---|
+| 1 | wheel install from PyPI | none | succeeds; static present |
+| 2 | sdist install from PyPI (`--no-binary :all:`) | none | succeeds; static present (backend short-circuits) |
+| 3 | source build (`uv build` from cloned tree) | with pnpm + Node | succeeds; wheel contains static |
+| 4 | source build (`uv build` from cloned tree) | none | fails with `PnpmMissingError` + CI-platform recipe |
+
+When you add a new failure mode or a new short-circuit branch, add a
+new row here AND a corresponding test in
+`tests/test_sphinx_vite_builder_vite.py`.
+
+## Architecture map
+
+```
+sphinx_vite_builder/
+├── __init__.py              Sphinx extension entry: setup(app)
+├── build.py                 PEP 517/660 hooks (delegate to hatchling)
+├── py.typed
+└── _internal/
+    ├── errors.py            SphinxViteBuilderError + 3 subclasses
+    ├── process.py           AsyncProcess (asyncio subprocess wrapper)
+    ├── bus.py               AsyncioBus (sync↔async bridge)
+    └── vite.py              run_vite_build() + CI detection + hint formatters
+```
+
+Neither head calls the other; both consume `_internal/`. The PEP 517
+hooks in `build.py` MUST stay 1:1 mirrors of `flit_core.buildapi` and
+`hatchling.build` — every hook runs `run_vite_build()` then delegates.
+Optional hooks (`get_requires_for_build_*`, `prepare_metadata_for_build_*`)
+alias to hatchling by identity — vite has no influence on dependency
+resolution or distribution metadata, so wrapping them would be wrong.
+
+## When you add a new public function
+
+- Add doctests. Every public function MUST have working doctests
+  per the workspace convention. Use ELLIPSIS for variable output.
+- Add NumPy-style docstrings: short summary, Parameters, Returns,
+  Raises, Examples.
+- Add type annotations everywhere, including return types
+  (`-> None` on test functions). mypy runs strict mode.
+
+## When you add a new error path
+
+- Add a new `*Error` subclass in `errors.py` if the failure has a
+  distinct semantic meaning. Inherit from `SphinxViteBuilderError`.
+- Add a `_format_*_hint(...)` function in `vite.py` for the
+  copy-pasteable diagnostic. Wrap the raise:
+  `raise NewError(_format_new_error_hint(...))`.
+- If the new path is reachable in CI, ensure the message includes
+  enough context to fix-from-the-message-itself. Add a CI-recipe
+  block via `_format_ci_recipe_block()` if relevant.
+- Add tests for: positive case (path triggers correctly), each error
+  branch (specific exception, with key strings present in message),
+  inheritance from `SphinxViteBuilderError`.
+
+## When you change `release.yml` or the workspace
+
+The workspace's `release.yml` MUST keep the pnpm + Node setup steps
+that run before `uv build`, otherwise the wheels published to PyPI
+would be empty of static (the prior broken-release pattern that
+motivated this whole package). The required steps are:
+
+```yaml
+- uses: pnpm/action-setup@v6
+  with:
+    version: 10
+- uses: actions/setup-node@v6
+  with:
+    node-version: 22
+    cache: pnpm
+```
+
+If you find yourself removing those, ask: "is the source-build path
+still going to produce a populated `static/` in the wheel?" The
+answer must be yes.
+
+## When in doubt
+
+- Read the full plan at gp-sphinx issue #28.
+- Look at how PR #29 wired everything together initially.
+- Look at how libtmux-mcp PR #33 exercises both consumer paths in
+  CI — the WITH-wheels and WITHOUT-wheels permutations both have
+  green runs that are good reference points.
+- Run the local QA matrix: clean venv install of the published
+  wheel, clean venv install of the published sdist (`--no-binary`),
+  clean clone + `uv build` with toolchain stripped (must fail
+  loudly), clean clone + `uv build` with toolchain present (must
+  succeed).
+
+## What NOT to do
+
+- **Do not** add `web/` to the sdist. Excluding it is what makes the
+  wheel-from-sdist short-circuit work.
+- **Do not** commit anything from `static/` to git. Build artefacts
+  are produced reproducibly; check-in is forbidden by workspace
+  policy.
+- **Do not** silently swallow vite/pnpm subprocess failures. Every
+  non-zero exit goes through a typed exception with a
+  copy-pasteable hint.
+- **Do not** auto-install pnpm via the backend (the maturin
+  `puccinialin`-style trick doesn't apply here — pnpm isn't
+  pip-installable). The contract is "pnpm is your responsibility,
+  here's how to install it on your platform".
+- **Do not** change `SPHINX_VITE_BUILDER_SKIP=1` semantics without
+  thinking through the wheel-vs-source asymmetry. The escape hatch
+  is correct for wheel-only environments; using it during a real
+  source build silently produces broken artefacts.

sphinx_vite_builder-0.0.1a16.dev2/CLAUDE.md

@@ -0,0 +1,8 @@
+# CLAUDE.md
+
+Claude Code reads this file. Other agent runners (Cursor, Copilot,
+Codex, …) read [`AGENTS.md`](AGENTS.md). The two files have identical
+content via this passthrough — every guideline lives in `AGENTS.md`,
+and edits go there.
+
+→ See [`AGENTS.md`](AGENTS.md).

sphinx_vite_builder-0.0.1a16.dev2/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: sphinx-vite-builder
+Version: 0.0.1a16.dev2
+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: 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.
+
+## The contract
+
+> **Sources should check for node, pnpm, etc and error if it's not
+> good, then build. Wheels should have the build files baked in and
+> not need node and pnpm at all.**
+
+This is the central invariant of the package. The two install paths
+behave asymmetrically by design:
+
+### Wheel installs — zero toolchain required
+
+A user running `pip install <package>` from PyPI gets a wheel that
+**already contains** the vite-built `static/` tree, populated by this
+backend at release time. The PEP 517 chain doesn't run on the
+consumer side. No backend invocation. No `pnpm`. No Node. The end
+user sees Python and only Python.
+
+No pnpm, no Node — just Python:
+
+```console
+$ pip install gp-furo-theme
+```
+
+### Source builds — fail loud, fail informatively
+
+A contributor (or downstream packager building from source) goes
+through the PEP 517 chain. The backend runs `pnpm exec vite build`
+to produce `static/`, and that requires pnpm + Node on PATH. If the
+toolchain is missing, the backend raises a typed exception with a
+multi-line, copy-pasteable hint:
+
+```
+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
+
+…
+
+Detected CI provider: GitHub Actions. Add the following to your pipeline
+config (before the Python build step that triggers this backend):
+
+          - uses: pnpm/action-setup@v6
+            with:
+              version: 10
+          - uses: actions/setup-node@v6
+            with:
+              node-version: 22
+              cache: pnpm
+```
+
+The error includes the resolved vite-root path, the platform-specific
+CI setup recipe (GitHub Actions, CircleCI, Azure Pipelines, GitLab CI,
+or generic), and the `SPHINX_VITE_BUILDER_SKIP=1` escape hatch for
+environments that genuinely don't need vite to run.
+
+### The `web/`-absent short-circuit (sdist install bridge)
+
+A user running `pip install <pkg>.tar.gz` from an sdist runs the
+PEP 517 chain too — but the sdist excludes `web/` (the Vite source
+tree). The backend detects the absence, short-circuits cleanly, and
+hatchling packs the pre-baked `static/` (carried in the sdist via
+`[tool.hatch.build] artifacts`) into the wheel. **Sdist installs
+need no toolchain either.**
+
+The asymmetry is the whole product: the same backend is strict
+(running and failing loudly) when there's a `web/` to act on, and
+silent (skipping cleanly) when there's no `web/` to begin with. The
+two shapes match the two consumer worlds.
+
+## 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"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["web/"]    # so the sdist→wheel chain hits the short-circuit
+
+[tool.hatch.build]
+artifacts = ["src/<your-theme>/theme/<theme-name>/static/"]
+```
+
+### Sphinx extension (Phase 1: placeholder)
+
+The extension entry point is currently a placeholder registered in
+`conf.py` to prevent import errors. Full lifecycle integration —
+running Vite before the docs build and spawning a watched Vite
+process during `sphinx-autobuild` — lands in a follow-up release.
+
+For now, the [PEP 517](https://peps.python.org/pep-0517/) backend
+handles all Vite orchestration during source builds and wheel
+generation; that path is fully implemented and tested.
+
+```python
+# docs/conf.py
+extensions = ["sphinx_vite_builder"]
+```
+
+## Fast-fail diagnostics — error type reference
+
+| Error | When | Hint surface |
+|---|---|---|
+| `PnpmMissingError` | `pnpm` not on `PATH` during a source build | `corepack enable`, [pnpm.io/installation](https://pnpm.io/installation), per-CI YAML recipe, `SPHINX_VITE_BUILDER_SKIP=1` |
+| `NodeModulesInstallError` | `pnpm install` exited non-zero | `cd <vite-root> && pnpm install --frozen-lockfile` rerun command, captured stderr |
+| `ViteFailedError` | `pnpm exec vite build` exited non-zero | invocation context (cwd, exit code), captured stderr |
+
+All three inherit from `SphinxViteBuilderError`, so consumers can
+`except SphinxViteBuilderError` for a single catch surface.
+
+## CI detection
+
+The `PnpmMissingError` hint is **self-healing** when the backend
+detects a CI environment. Detection precedence (most-specific wins):
+
+| CI provider | Env var | Recipe shape |
+|---|---|---|
+| GitHub Actions | `GITHUB_ACTIONS=true` | `pnpm/action-setup@v6` + `actions/setup-node@v6` |
+| CircleCI | `CIRCLECI=true` | `corepack enable && corepack prepare pnpm@latest-10 --activate` step |
+| Azure Pipelines | `TF_BUILD=True` | `NodeTool@0` + corepack script |
+| GitLab CI | `GITLAB_CI=true` | `before_script` corepack invocations |
+| Generic | `CI=true` | "Use your CI's package-manager setup mechanism" |
+
+Source: each provider's own canonical detection variable per the pnpm
+[Continuous Integration docs](https://pnpm.io/continuous-integration).
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Agent / contributor guidance
+
+See [`AGENTS.md`](AGENTS.md) for the design contract, architecture
+map, and conventions agents and contributors should follow when
+making changes. ([`CLAUDE.md`](CLAUDE.md) is a passthrough to
+`AGENTS.md` for Claude Code.)

sphinx_vite_builder-0.0.1a16.dev2/README.md

@@ -0,0 +1,173 @@
+# 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.
+
+## The contract
+
+> **Sources should check for node, pnpm, etc and error if it's not
+> good, then build. Wheels should have the build files baked in and
+> not need node and pnpm at all.**
+
+This is the central invariant of the package. The two install paths
+behave asymmetrically by design:
+
+### Wheel installs — zero toolchain required
+
+A user running `pip install <package>` from PyPI gets a wheel that
+**already contains** the vite-built `static/` tree, populated by this
+backend at release time. The PEP 517 chain doesn't run on the
+consumer side. No backend invocation. No `pnpm`. No Node. The end
+user sees Python and only Python.
+
+No pnpm, no Node — just Python:
+
+```console
+$ pip install gp-furo-theme
+```
+
+### Source builds — fail loud, fail informatively
+
+A contributor (or downstream packager building from source) goes
+through the PEP 517 chain. The backend runs `pnpm exec vite build`
+to produce `static/`, and that requires pnpm + Node on PATH. If the
+toolchain is missing, the backend raises a typed exception with a
+multi-line, copy-pasteable hint:
+
+```
+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
+
+…
+
+Detected CI provider: GitHub Actions. Add the following to your pipeline
+config (before the Python build step that triggers this backend):
+
+          - uses: pnpm/action-setup@v6
+            with:
+              version: 10
+          - uses: actions/setup-node@v6
+            with:
+              node-version: 22
+              cache: pnpm
+```
+
+The error includes the resolved vite-root path, the platform-specific
+CI setup recipe (GitHub Actions, CircleCI, Azure Pipelines, GitLab CI,
+or generic), and the `SPHINX_VITE_BUILDER_SKIP=1` escape hatch for
+environments that genuinely don't need vite to run.
+
+### The `web/`-absent short-circuit (sdist install bridge)
+
+A user running `pip install <pkg>.tar.gz` from an sdist runs the
+PEP 517 chain too — but the sdist excludes `web/` (the Vite source
+tree). The backend detects the absence, short-circuits cleanly, and
+hatchling packs the pre-baked `static/` (carried in the sdist via
+`[tool.hatch.build] artifacts`) into the wheel. **Sdist installs
+need no toolchain either.**
+
+The asymmetry is the whole product: the same backend is strict
+(running and failing loudly) when there's a `web/` to act on, and
+silent (skipping cleanly) when there's no `web/` to begin with. The
+two shapes match the two consumer worlds.
+
+## 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"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["web/"]    # so the sdist→wheel chain hits the short-circuit
+
+[tool.hatch.build]
+artifacts = ["src/<your-theme>/theme/<theme-name>/static/"]
+```
+
+### Sphinx extension (Phase 1: placeholder)
+
+The extension entry point is currently a placeholder registered in
+`conf.py` to prevent import errors. Full lifecycle integration —
+running Vite before the docs build and spawning a watched Vite
+process during `sphinx-autobuild` — lands in a follow-up release.
+
+For now, the [PEP 517](https://peps.python.org/pep-0517/) backend
+handles all Vite orchestration during source builds and wheel
+generation; that path is fully implemented and tested.
+
+```python
+# docs/conf.py
+extensions = ["sphinx_vite_builder"]
+```
+
+## Fast-fail diagnostics — error type reference
+
+| Error | When | Hint surface |
+|---|---|---|
+| `PnpmMissingError` | `pnpm` not on `PATH` during a source build | `corepack enable`, [pnpm.io/installation](https://pnpm.io/installation), per-CI YAML recipe, `SPHINX_VITE_BUILDER_SKIP=1` |
+| `NodeModulesInstallError` | `pnpm install` exited non-zero | `cd <vite-root> && pnpm install --frozen-lockfile` rerun command, captured stderr |
+| `ViteFailedError` | `pnpm exec vite build` exited non-zero | invocation context (cwd, exit code), captured stderr |
+
+All three inherit from `SphinxViteBuilderError`, so consumers can
+`except SphinxViteBuilderError` for a single catch surface.
+
+## CI detection
+
+The `PnpmMissingError` hint is **self-healing** when the backend
+detects a CI environment. Detection precedence (most-specific wins):
+
+| CI provider | Env var | Recipe shape |
+|---|---|---|
+| GitHub Actions | `GITHUB_ACTIONS=true` | `pnpm/action-setup@v6` + `actions/setup-node@v6` |
+| CircleCI | `CIRCLECI=true` | `corepack enable && corepack prepare pnpm@latest-10 --activate` step |
+| Azure Pipelines | `TF_BUILD=True` | `NodeTool@0` + corepack script |
+| GitLab CI | `GITLAB_CI=true` | `before_script` corepack invocations |
+| Generic | `CI=true` | "Use your CI's package-manager setup mechanism" |
+
+Source: each provider's own canonical detection variable per the pnpm
+[Continuous Integration docs](https://pnpm.io/continuous-integration).
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Agent / contributor guidance
+
+See [`AGENTS.md`](AGENTS.md) for the design contract, architecture
+map, and conventions agents and contributors should follow when
+making changes. ([`CLAUDE.md`](CLAUDE.md) is a passthrough to
+`AGENTS.md` for Claude Code.)

{sphinx_vite_builder-0.0.1a16.dev0 → sphinx_vite_builder-0.0.1a16.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sphinx-vite-builder"
-version = "0.0.1a16.dev0"
+version = "0.0.1a16.dev2"
 description = "PEP 517 build backend + Sphinx extension that orchestrates Vite via pnpm"
 requires-python = ">=3.10,<4.0"
 authors = [
@@ -31,7 +31,6 @@ keywords = ["sphinx", "extension", "vite", "pnpm", "pep517", "build", "backend"]
 # required at build time of consumer packages but not at runtime, so it
 # stays in [build-system].requires of *consumers* rather than here.
 dependencies = [
-  "hatchling>=1.0",
   "sphinx>=8.1",
 ]
 

{sphinx_vite_builder-0.0.1a16.dev0 → sphinx_vite_builder-0.0.1a16.dev2}/src/sphinx_vite_builder/__init__.py

@@ -15,9 +15,13 @@ under :mod:`sphinx_vite_builder._internal`.
 
 from __future__ import annotations
 
+import logging
 import typing as t
 
-__version__ = "0.0.1a16.dev0"
+__version__ = "0.0.1a16.dev2"
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
 
 if t.TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -31,6 +35,19 @@ def setup(app: Sphinx) -> dict[str, t.Any]:
     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.
+
+    Examples
+    --------
+    The Phase-1 stub returns the parallel-safety metadata Sphinx
+    expects, regardless of the application object passed in:
+
+    >>> class FakeApp:
+    ...     pass
+    >>> metadata = setup(FakeApp())  # type: ignore[arg-type]
+    >>> metadata["parallel_read_safe"]
+    True
+    >>> metadata["parallel_write_safe"]
+    True
     """
     del app
     return {

{sphinx_vite_builder-0.0.1a16.dev0 → sphinx_vite_builder-0.0.1a16.dev2}/src/sphinx_vite_builder/_internal/process.py

@@ -9,9 +9,11 @@ backend and extension heads need:
 - ``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).
+  and :meth:`AsyncProcess.terminate` signals the whole process group
+  via :func:`os.killpg` so ``pnpm exec`` plus every descendant exits
+  together. ``asyncio.subprocess.Process.terminate`` would only signal
+  the leader's PID, leaving the vite child orphaned (pnpm does not
+  forward signals to its ``exec`` target).
 - :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
@@ -32,6 +34,7 @@ import contextlib
 import logging
 import os
 import pathlib
+import signal
 import sys
 import typing as t
 
@@ -196,7 +199,19 @@ class AsyncProcess:
         if self._process.returncode is not None:
             return self._process.returncode
 
-        self._process.terminate()
+        # POSIX: the child was spawned with ``start_new_session=True``,
+        # so ``self._process.pid`` is the leader of its own session and
+        # equals its process-group ID. SIGTERM the whole group so
+        # ``pnpm exec`` plus all its descendants (including the vite
+        # process pnpm doesn't forward signals to) exit. asyncio's
+        # ``Process.terminate()`` is PID-only — it would leave vite
+        # orphaned. Windows has no ``killpg``; the asyncio default is
+        # the right primitive there.
+        with contextlib.suppress(ProcessLookupError):
+            if sys.platform != "win32":
+                os.killpg(self._process.pid, signal.SIGTERM)
+            else:
+                self._process.terminate()
         try:
             await asyncio.wait_for(self._process.wait(), timeout=timeout)
         except asyncio.TimeoutError:
@@ -208,7 +223,10 @@ class AsyncProcess:
             # ProcessLookupError race: the child can exit between
             # TimeoutError and kill().
             with contextlib.suppress(ProcessLookupError):
-                self._process.kill()
+                if sys.platform != "win32":
+                    os.killpg(self._process.pid, signal.SIGKILL)
+                else:
+                    self._process.kill()
             await self._process.wait()
 
         # Wait for drainers to consume their last buffered line before

{sphinx_vite_builder-0.0.1a16.dev0 → sphinx_vite_builder-0.0.1a16.dev2}/src/sphinx_vite_builder/_internal/vite.py

@@ -1,13 +1,14 @@
-"""Vite + pnpm orchestration: detection, install, one-shot build, watch.
+"""Vite + pnpm orchestration: detection, install, one-shot build.
 
 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``.
+- The Sphinx extension (:mod:`sphinx_vite_builder`) — Phase 1
+  placeholder — will call :func:`run_vite_build` from
+  ``builder-inited`` once the extension head lands in a follow-up
+  release.
 
 Fast-fail discipline: every prerequisite is checked up front so the
 caller gets an actionable diagnostic instead of a generic spawn-failure
@@ -340,6 +341,22 @@ def run_vite_build(
       non-zero.
     - :class:`ViteFailedError` if ``pnpm exec vite build`` exits
       non-zero.
+
+    Examples
+    --------
+    The ``SPHINX_VITE_BUILDER_SKIP`` environment variable
+    short-circuits the whole orchestration before any subprocess is
+    spawned — exercising it from a doctest verifies the escape hatch
+    keeps working without touching pnpm, Node, or the filesystem
+    tree:
+
+    >>> import os, pathlib, tempfile
+    >>> os.environ["SPHINX_VITE_BUILDER_SKIP"] = "1"
+    >>> try:
+    ...     with tempfile.TemporaryDirectory() as tmp:
+    ...         run_vite_build(pathlib.Path(tmp))
+    ... finally:
+    ...     del os.environ["SPHINX_VITE_BUILDER_SKIP"]
     """
     if os.environ.get("SPHINX_VITE_BUILDER_SKIP"):
         logger.info("SPHINX_VITE_BUILDER_SKIP set; skipping vite build")

{sphinx_vite_builder-0.0.1a16.dev0 → sphinx_vite_builder-0.0.1a16.dev2}/src/sphinx_vite_builder/build.py

@@ -37,7 +37,41 @@ def build_wheel(
     config_settings: dict[str, t.Any] | None = None,
     metadata_directory: str | None = None,
 ) -> str:
-    """PEP 517 ``build_wheel``: vite-build, then hatchling-pack."""
+    """PEP 517 ``build_wheel``: vite-build, then hatchling-pack.
+
+    Examples
+    --------
+    With ``SPHINX_VITE_BUILDER_SKIP=1`` set, the hook short-circuits
+    vite and delegates straight to :mod:`hatchling.build` against a
+    minimal synthetic project, producing a real ``.whl``:
+
+    >>> import os, pathlib, tempfile, textwrap
+    >>> os.environ["SPHINX_VITE_BUILDER_SKIP"] = "1"
+    >>> cwd = os.getcwd()
+    >>> with tempfile.TemporaryDirectory() as tmp:
+    ...     project = pathlib.Path(tmp)
+    ...     _ = (project / "pyproject.toml").write_text(textwrap.dedent('''
+    ...         [build-system]
+    ...         requires = ["hatchling"]
+    ...         build-backend = "hatchling.build"
+    ...         [project]
+    ...         name = "doctest-pkg"
+    ...         version = "0.0.0"
+    ...     ''').lstrip())
+    ...     pkg = project / "doctest_pkg"
+    ...     pkg.mkdir()
+    ...     _ = (pkg / "__init__.py").write_text("")
+    ...     dist = project / "dist"
+    ...     dist.mkdir()
+    ...     os.chdir(project)
+    ...     try:
+    ...         name = build_wheel(str(dist))
+    ...     finally:
+    ...         os.chdir(cwd)
+    ...         del os.environ["SPHINX_VITE_BUILDER_SKIP"]
+    >>> name.endswith(".whl")
+    True
+    """
     run_vite_build()
     return _hatchling.build_wheel(wheel_directory, config_settings, metadata_directory)
 
@@ -47,7 +81,18 @@ def build_editable(
     config_settings: dict[str, t.Any] | None = None,
     metadata_directory: str | None = None,
 ) -> str:
-    """PEP 660 ``build_editable``: vite-build, then hatchling-pack-editable."""
+    """PEP 660 ``build_editable``: vite-build, then hatchling-pack-editable.
+
+    The delegation pattern matches :func:`build_wheel`; see that
+    function's docstring for an end-to-end example exercising the
+    ``SPHINX_VITE_BUILDER_SKIP=1`` short-circuit.
+
+    Examples
+    --------
+    >>> import inspect
+    >>> sorted(inspect.signature(build_editable).parameters)
+    ['config_settings', 'metadata_directory', 'wheel_directory']
+    """
     run_vite_build()
     return _hatchling.build_editable(
         wheel_directory, config_settings, metadata_directory
@@ -66,6 +111,16 @@ def build_sdist(
     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.
+
+    The delegation pattern matches :func:`build_wheel`; see that
+    function's docstring for an end-to-end example exercising the
+    ``SPHINX_VITE_BUILDER_SKIP=1`` short-circuit.
+
+    Examples
+    --------
+    >>> import inspect
+    >>> sorted(inspect.signature(build_sdist).parameters)
+    ['config_settings', 'sdist_directory']
     """
     run_vite_build()
     return _hatchling.build_sdist(sdist_directory, config_settings)

sphinx_vite_builder-0.0.1a16.dev0/PKG-INFO

@@ -1,106 +0,0 @@
-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/README.md

@@ -1,78 +0,0 @@
-# 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).