P9-T4 Create publishing helper

Makefile

@@ -1,6 +1,6 @@
 # Makefile for mcpbridge-wrapper
 
-.PHONY: help install install-webui test test-webui lint format format-check typecheck doccheck doccheck-staged doccheck-branch doccheck-all package-assets-check clean webui webui-health check
+.PHONY: help install install-webui test test-webui lint format format-check typecheck doccheck doccheck-staged doccheck-branch doccheck-all package-assets-check bump-version clean webui webui-health check
 
 help:
 	@echo "Available targets:"
@@ -17,6 +17,7 @@ help:
 	@echo "  doccheck-branch - Check docs/ sync against git branch"
 	@echo "  doccheck-all   - Check docs/ sync for unstaged, staged, and branch changes"
 	@echo "  package-assets-check - Build artifacts and verify required packaged assets"
+	@echo "  bump-version   - Update pyproject.toml and server.json versions (VERSION=x.y.z, add DRY_RUN=1 to preview)"
 	@echo "  webui          - Start wrapper with Web UI dashboard (port 8080)"
 	@echo "  webui-health   - Check Web UI health status"
 	@echo "  clean          - Clean build artifacts"
@@ -72,6 +73,17 @@ package-assets-check:
 	python -m build --sdist --wheel
 	python scripts/check_package_assets.py --dist-dir dist
 
+bump-version:
+	@if [ -z "$(VERSION)" ]; then \
+		echo "Usage: make bump-version VERSION=x.y.z [DRY_RUN=1]"; \
+		exit 1; \
+	fi
+	@if [ -n "$(DRY_RUN)" ]; then \
+		python scripts/publish_helper.py $(VERSION) --dry-run; \
+	else \
+		python scripts/publish_helper.py $(VERSION); \
+	fi
+
 check: test lint format-check typecheck doccheck-all package-assets-check
 
 clean:

PUBLISHING.md

@@ -68,24 +68,50 @@ No additional secrets needed! The workflow uses GitHub OIDC for authentication.
 
 ## How to Publish
 
+### Version Helper (Recommended for Version Bumps)
+
+Use the helper to update all required version fields together:
+
+```bash
+# Preview changes only
+python scripts/publish_helper.py 0.4.0 --dry-run
+
+# Apply changes
+python scripts/publish_helper.py 0.4.0
+```
+
+Or via Makefile:
+
+```bash
+make bump-version VERSION=0.4.0 DRY_RUN=1
+make bump-version VERSION=0.4.0
+```
+
+The helper updates:
+- `pyproject.toml` → `[project].version`
+- `server.json` → top-level `version`
+- `server.json` → `packages[*].version`
+
+It also prints the next release commands (`git add`, `git commit`, `git tag`, `git push`) aligned with this guide.
+
 ### Automated Publishing (Recommended)
 
-1. **Update version** in `pyproject.toml` and `server.json`:
-   ```toml
-   version = "0.2.0"
+1. **Update version** (recommended: helper script):
+   ```bash
+   python scripts/publish_helper.py 0.4.0
    ```
 
 2. **Commit and push**:
    ```bash
    git add pyproject.toml server.json
-   git commit -m "Bump version to 0.2.0"
+   git commit -m "Bump version to 0.4.0"
    git push
    ```
 
 3. **Create and push a tag**:
    ```bash
-   git tag v0.2.0
-   git push origin v0.2.0
+   git tag v0.4.0
+   git push origin v0.4.0
    ```
 
 4. **Watch the workflow run**:

SPECS/ARCHIVE/INDEX.md

@@ -80,6 +80,7 @@
 | FU-REBUILD-P10-T1-7 | [FU-REBUILD-P10-T1-7_WebUI_Static_Assets/](FU-REBUILD-P10-T1-7_WebUI_Static_Assets/) | 2026-02-13 | PASS |
 | FU-P9-T2-1 | [FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/](FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/) | 2026-02-13 | PASS |
 | BUG-T0 | [BUG-T0_Uptime_Widget_Fix/](BUG-T0_Uptime_Widget_Fix/) | 2026-02-13 | PASS |
+| P9-T4 | [P9-T4_Create_the_publishing_helper/](P9-T4_Create_the_publishing_helper/) | 2026-02-13 | PASS |
 
 ## Historical Artifacts
 
@@ -125,6 +126,7 @@
 | [REVIEW_webui-static-assets.md](FU-REBUILD-P10-T1-7_WebUI_Static_Assets/REVIEW_webui-static-assets.md) | Review report for FU-REBUILD-P10-T1-7 |
 | [REVIEW_fu_p9_t2_1_uvx_webui_extras.md](FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/REVIEW_fu_p9_t2_1_uvx_webui_extras.md) | Review report for FU-P9-T2-1 |
 | [REVIEW_BUG-T0_Uptime_Widget.md](BUG-T0_Uptime_Widget_Fix/REVIEW_BUG-T0_Uptime_Widget.md) | Review report for BUG-T0 |
+| [REVIEW_p9_t4_publishing_helper.md](P9-T4_Create_the_publishing_helper/REVIEW_p9_t4_publishing_helper.md) | Review report for P9-T4 |
 
 ## Archive Log
 
@@ -204,3 +206,5 @@
 | 2026-02-13 | FU-P9-T2-1 | Archived REVIEW_fu_p9_t2_1_uvx_webui_extras report |
 | 2026-02-13 | BUG-T0 | Archived Uptime_Widget_Fix (PASS) |
 | 2026-02-13 | BUG-T0 | Archived REVIEW_BUG-T0_Uptime_Widget report |
+| 2026-02-13 | P9-T4 | Archived Create_the_publishing_helper (PASS) |
+| 2026-02-13 | P9-T4 | Archived REVIEW_p9_t4_publishing_helper report |

SPECS/ARCHIVE/P9-T4_Create_the_publishing_helper/P9-T4_Create_the_publishing_helper.md

@@ -0,0 +1,58 @@
+# P9-T4 — Create the publishing helper
+
+**Task ID:** P9-T4  
+**Phase:** Phase 9: Release Management  
+**Priority:** P1  
+**Dependencies:** P9-T3  
+**Status:** Planned
+
+## Objective
+
+Create a publishing helper script that reduces release errors by performing version bumps in all required files from a single command. The helper must validate a provided semantic version, update both `pyproject.toml` and `server.json` consistently, and support `--dry-run` to preview changes safely. It should also print the exact next commands required to complete release publication according to `PUBLISHING.md`.
+
+## Success Criteria
+
+- A helper exists at `scripts/publish_helper.py` and is executable via `python scripts/publish_helper.py <version>`.
+- Semantic versions in `MAJOR.MINOR.PATCH` format are accepted; invalid values are rejected with non-zero exit code and clear error.
+- Both `pyproject.toml` and `server.json` are updated to the same target version in one run.
+- Dry-run mode outputs planned file changes and does not modify files.
+- Script output includes next-step release commands for commit/tag/push and notes that GitHub Actions handles publish.
+- `PUBLISHING.md` documents helper usage.
+- Quality gates pass: `pytest`, `ruff check src/`, `mypy src/`, `pytest --cov` with coverage >= 90%.
+
+## Test-First Plan
+
+1. Add unit tests covering:
+   - valid version updates,
+   - invalid version rejection,
+   - dry-run no-write behavior,
+   - mismatch detection for expected keys and output summary behavior.
+2. Implement helper internals to satisfy tests.
+3. Update publishing docs and rerun targeted and full test suites.
+
+## Execution Plan
+
+### Phase A: Script Design and CLI Contract
+- **Inputs:** `PUBLISHING.md`, `pyproject.toml`, `server.json`
+- **Outputs:** CLI arguments and validation rules, parsing/update logic
+- **Verification:** `--help` output and unit tests for parser/validator
+
+### Phase B: Implementation and File Updates
+- **Inputs:** target version argument and repository files
+- **Outputs:** updated `scripts/publish_helper.py`, modified version fields
+- **Verification:** tests assert exact replacements and dry-run preservation
+
+### Phase C: Docs and Integration Validation
+- **Inputs:** final script behavior
+- **Outputs:** updated `PUBLISHING.md`, optional Makefile helper target
+- **Verification:** full quality gates and manual dry-run/live-run checks
+
+## Notes
+
+- Keep logic deterministic and avoid external dependencies.
+- Fail fast if expected version keys are missing or ambiguous.
+- Preserve JSON formatting and TOML readability when writing updates.
+
+---
+**Archived:** 2026-02-13
+**Verdict:** PASS

SPECS/ARCHIVE/P9-T4_Create_the_publishing_helper/P9-T4_Validation_Report.md

@@ -0,0 +1,44 @@
+# Validation Report — P9-T4: Create the publishing helper
+
+**Date:** 2026-02-13  
+**Verdict:** PASS
+
+## Scope
+
+Implemented a new publishing helper to perform coordinated version updates for release publishing, documented usage in publishing docs, and added tests.
+
+## Deliverables
+
+- `scripts/publish_helper.py` created
+- `tests/unit/test_publish_helper.py` created
+- `PUBLISHING.md` updated with helper usage and Makefile examples
+- `Makefile` updated with `bump-version` target
+
+## Acceptance Criteria Check
+
+- [x] Running helper updates `pyproject.toml` and `server.json` to same version
+- [x] Invalid semantic versions are rejected with clear error
+- [x] `--dry-run` prints planned changes and does not modify files
+- [x] Helper prints release commands (`git add`, `commit`, `tag`, `push`)
+- [x] Existing tests and quality gates pass
+
+## Commands Executed
+
+- `pytest tests/unit/test_publish_helper.py -v`
+- `pytest`
+- `ruff check src/`
+- `mypy src/`
+- `pytest --cov`
+- `python scripts/publish_helper.py 0.3.3 --dry-run`
+
+## Results
+
+- `pytest`: PASS (`345 passed, 5 skipped`)
+- `ruff check src/`: PASS
+- `mypy src/`: PASS
+- `pytest --cov`: PASS (`Total coverage: 96.62%`, threshold 90%)
+- Manual dry-run of helper: PASS (correct planned updates and guidance output)
+
+## Notes
+
+Test warnings seen during full suite were pre-existing environment/runtime warnings (websocket deprecations and transient port 8080 binding from threaded Web UI test), not regressions from this task.

SPECS/ARCHIVE/P9-T4_Create_the_publishing_helper/REVIEW_p9_t4_publishing_helper.md

@@ -0,0 +1,38 @@
+## REVIEW REPORT — P9-T4 Publishing Helper
+
+**Scope:** origin/main..HEAD  
+**Files:** 9
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+
+None.
+
+### Secondary Issues
+
+None.
+
+### Architectural Notes
+
+- `scripts/publish_helper.py` uses deterministic local file transformations with explicit validation and no network/runtime side effects.
+- The helper keeps release version updates centralized and reduces drift risk between `pyproject.toml` and `server.json`.
+- Dry-run behavior and explicit next-step command output align with documented publishing workflow.
+
+### Tests
+
+- Added: `tests/unit/test_publish_helper.py` (17 tests)
+- Executed quality gates:
+  - `pytest`
+  - `ruff check src/`
+  - `mypy src/`
+  - `pytest --cov`
+- Coverage remained above threshold: `96.62%` (required `>= 90%`).
+
+### Next Steps
+
+- FOLLOW-UP skipped: no actionable findings from review.

SPECS/INPROGRESS/next.md

@@ -4,11 +4,11 @@ The previously selected task has been archived.
 
 ## Recently Archived
 
+- 2026-02-13 — P9-T4: Create the publishing helper (PASS)
 - 2026-02-13 — BUG-T0: Uptime widget on Web UI always shows 1h 0m 0s (PASS)
 - 2026-02-13 — FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras (PASS)
 - 2026-02-13 — FU-REBUILD-P10-T1-7: Include Web UI static assets in published package artifacts (PASS)
 - 2026-02-13 — P9-T3: Release version 0.3.0 (Web UI Feature Release) (PASS)
-- 2026-02-12 — FU-P8-T1-1: Reconcile P8-T1 URL criteria with current GitHub Pages path and resolve DocC reference warnings (PASS)
 
 ## Suggested Next Tasks
 

SPECS/Workplan.md

@@ -1194,6 +1194,24 @@ Main branch is currently unstable after an accidental merge of the Phase 10 Web
 
 ---
 
+#### ✅ P9-T4: Create the publishing helper
+- **Description:** Create a helper script to streamline release version updates for publishing. The script should update all required version fields in one run (at minimum `pyproject.toml` and `server.json`), validate the provided semantic version, and guide the user through the remaining publish steps documented in `PUBLISHING.md`.
+- **Priority:** P1
+- **Dependencies:** P9-T3
+- **Parallelizable:** yes
+- **Outputs/Artifacts:**
+  - New helper script at `scripts/publish_helper.py` (or equivalent script under `scripts/`)
+  - Documentation update in `PUBLISHING.md` showing how to run the helper
+  - Optional `Makefile` convenience target for version bumping
+- **Acceptance Criteria:**
+  - Running the helper with a target version updates `pyproject.toml` and `server.json` to the exact same version value
+  - The helper rejects invalid version formats with a clear error message
+  - The helper supports a dry-run mode that prints planned changes without modifying files
+  - The helper prints next release commands (commit, tag, push) aligned with `PUBLISHING.md`
+  - Existing tests and quality gates continue to pass after integrating the helper
+
+---
+
 Phase 9 Follow-up Backlog
 - [x] FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras (P1)