sphinx-vite-builder 0.0.1a16__tar.gz

sphinx_vite_builder-0.0.1a16/.gitignore

@@ -0,0 +1,233 @@
+# Node
+node_modules/
+*.tsbuildinfo
+.vitest-cache/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Generated by sphinx_fonts extension (downloaded at build time)
+docs/_static/fonts/
+docs/_static/css/fonts.css
+
+# Claude Code
+**/CLAUDE.local.md
+**/CLAUDE.*.md
+**/.claude/settings.local.json
+
+# Playwright MCP
+.playwright-mcp/
+
+# Repo-local pytest mirror (do not track — validator-only)
+out/
+
+# Misc
+.vim/
+*.lprof
+pip-wheel-metadata/
+monkeytype.sqlite3

sphinx_vite_builder-0.0.1a16/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/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).