feat: add sync-pyproject target to non-destructively patch pyproject.toml via template.yml

.rhiza/docs/TEMPLATE_YML_EXAMPLE.md

@@ -0,0 +1,117 @@
+# `.rhiza/template.yml` Example with `pyproject:` Section
+
+This document shows a fully-annotated example of a downstream project's
+`.rhiza/template.yml` using the optional `pyproject:` section introduced by
+the `sync-pyproject` feature.
+
+---
+
+## Full Example
+
+```yaml
+# .rhiza/template.yml
+# ---------------------------------------------------------------
+# Which rhiza release to sync against
+repository: Jebel-Quant/rhiza
+ref: v0.9.0
+
+# Which template bundles to enable
+templates:
+  - core
+  - tests
+  - github
+
+# ---------------------------------------------------------------
+# Fields rhiza controls in pyproject.toml (all optional)
+#
+# Only the keys declared here are touched during `make sync-pyproject`.
+# Everything else in pyproject.toml (name, version, description, authors,
+# keywords, dependencies, [dependency-groups], [project.urls]) is
+# preserved unchanged.
+# ---------------------------------------------------------------
+pyproject:
+
+  # Set [project].requires-python
+  requires-python: ">=3.11"
+
+  # Set [project].license — accepts a plain string (PEP 639) ...
+  license: "MIT"
+  # ... or an inline table (PEP 517):
+  # license:
+  #   text: "MIT"
+  # license:
+  #   file: "LICENSE"
+
+  # Set [project].readme (file path string)
+  readme: "README.md"
+
+  # Replace [project].classifiers entirely.
+  # Rhiza owns this list — it mirrors the requires-python / .python-version
+  # support matrix.
+  classifiers:
+    - "Programming Language :: Python :: 3"
+    - "Programming Language :: Python :: 3 :: Only"
+    - "Programming Language :: Python :: 3.11"
+    - "Programming Language :: Python :: 3.12"
+    - "Programming Language :: Python :: 3.13"
+    - "Programming Language :: Python :: 3.14"
+    - "License :: OSI Approved :: MIT License"
+    - "Intended Audience :: Developers"
+
+  # Sync entire [tool.*] subsections from rhiza's own pyproject.toml.
+  # Use dotted TOML paths — the entire subtree at that path is replaced.
+  tool-sections:
+    - tool.deptry.package_module_name_map
+```
+
+---
+
+## Supported `pyproject:` Keys
+
+| Key | TOML path patched | Behaviour |
+|-----|-------------------|-----------|
+| `requires-python` | `[project].requires-python` | Sets the value; no-op if already matching |
+| `classifiers` | `[project].classifiers` | Replaces the list entirely |
+| `license` | `[project].license` | Accepts a plain string (`"MIT"`) or a mapping (`{text: "MIT"}`) |
+| `readme` | `[project].readme` | Sets the readme file path string |
+| `tool-sections` | `[tool.<...>]` (dotted path) | Syncs the subtree from rhiza's own `pyproject.toml` |
+
+---
+
+## Running the Sync
+
+```bash
+# Apply changes
+make sync-pyproject
+
+# Preview without writing
+make sync-pyproject DRY_RUN=1
+
+# CI check — exits non-zero if changes are needed
+make sync-pyproject CHECK=1
+```
+
+Or call the script directly:
+
+```bash
+uv run python .rhiza/utils/sync_pyproject.py
+uv run python .rhiza/utils/sync_pyproject.py --dry-run
+uv run python .rhiza/utils/sync_pyproject.py --check
+```
+
+---
+
+## What is Never Touched
+
+The following fields are **never modified** by `sync-pyproject` unless you
+add them to a supported key above:
+
+- `name`
+- `version`
+- `description`
+- `authors`
+- `keywords`
+- `dependencies`
+- `[dependency-groups]`
+- `[project.urls]`
+- Any `[tool.*]` section not listed under `tool-sections`

.rhiza/docs/WORKFLOWS.md

@@ -213,6 +213,33 @@ make sync
 
 This updates shared configurations while preserving your customizations in `local.mk`.
 
+## `pyproject.toml` Field Synchronization
+
+Rhiza can non-destructively patch selected fields in your `pyproject.toml`
+via the optional `pyproject:` section in `.rhiza/template.yml`.
+
+Fields rhiza can control (all opt-in):
+- `requires-python` — keeps the Python version constraint in sync
+- `classifiers` — mirrors the supported Python version matrix
+- `tool-sections` — syncs `[tool.*]` subtrees from rhiza's own `pyproject.toml`
+
+Everything else (`name`, `version`, `description`, `authors`, `dependencies`,
+`[dependency-groups]`, `[project.urls]`) is **never touched**.
+
+```bash
+# Apply changes defined in .rhiza/template.yml [pyproject:] section
+make sync-pyproject
+
+# Preview without writing
+make sync-pyproject DRY_RUN=1
+
+# CI check — exits non-zero if changes are pending
+make sync-pyproject CHECK=1
+```
+
+See `.rhiza/docs/TEMPLATE_YML_EXAMPLE.md` for a fully-annotated example
+of the `pyproject:` section.
+
 ## Troubleshooting
 
 ### Environment Out of Sync

.rhiza/make.d/releasing.mk

@@ -2,7 +2,7 @@
 # This file provides targets for version bumping and release management.
 
 # Declare phony targets (they don't produce files)
-.PHONY: bump release publish release-status pre-bump post-bump pre-release post-release
+.PHONY: bump release publish release-status sync-pyproject pre-bump post-bump pre-release post-release
 
 # Hook targets (double-colon rules allow multiple definitions)
 pre-bump:: ; @:
@@ -46,5 +46,16 @@ else
 	@printf "${RED}[ERROR] Could not detect forge type (.github/workflows/ or .gitlab-ci.yml not found)${RESET}\n"
 endif
 
+sync-pyproject: ## sync pyproject.toml fields from .rhiza/template.yml (supports DRY_RUN=1, CHECK=1)
+	@if [ -f "pyproject.toml" ] && [ -f ".rhiza/template.yml" ]; then \
+		$(MAKE) install; \
+		_FLAGS=""; \
+		if [ -n "$(DRY_RUN)" ]; then _FLAGS="$$_FLAGS --dry-run"; fi; \
+		if [ -n "$(CHECK)" ]; then _FLAGS="$$_FLAGS --check"; fi; \
+		${UV_BIN} run python .rhiza/utils/sync_pyproject.py $$_FLAGS; \
+	else \
+		printf "${YELLOW}[WARN] pyproject.toml or .rhiza/template.yml not found, skipping sync-pyproject${RESET}\n"; \
+	fi
+
 
 

.rhiza/requirements/tools.txt

@@ -5,3 +5,5 @@ python-dotenv==1.2.1
 # for now needed until rhiza-tools is finished
 typer==0.21.1
 ty==0.0.18
+
+tomlkit>=0.13,<1.0

.rhiza/template-bundles.yml

@@ -48,6 +48,7 @@ bundles:
       - .rhiza/requirements/README.md
       - .rhiza/requirements/docs.txt
       - .rhiza/requirements/tools.txt
+      - .rhiza/utils/sync_pyproject.py
 
       # Root configuration files
       - Makefile