diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 105049d..a5f7945 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -6,6 +6,7 @@ | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| +| P1-T13 | [P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/](P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/) | 2026-03-10 | PASS | | P2-T8 | [P2-T8_Gate_broker_tools_list_on_warmed_tool_catalog/](P2-T8_Gate_broker_tools_list_on_warmed_tool_catalog/) | 2026-03-10 | PASS | | P8-T1 | [P8-T1_Release_version_0.4.2_to_PyPI_and_MCP_Registry/](P8-T1_Release_version_0.4.2_to_PyPI_and_MCP_Registry/) | 2026-03-07 | PASS | | P7-T5 | [P7-T5_Document_broker_UX/](P7-T5_Document_broker_UX/) | 2026-03-07 | PASS | @@ -206,6 +207,7 @@ | File | Description | |------|-------------| +| [REVIEW_p1_t13_editable_install_troubleshooting.md](_Historical/REVIEW_p1_t13_editable_install_troubleshooting.md) | Review report for P1-T13 | | [REVIEW_p2_t8_tools_catalog_gate.md](_Historical/REVIEW_p2_t8_tools_catalog_gate.md) | Review report for P2-T8 | | [REVIEW_broker_ux_docs.md](_Historical/REVIEW_broker_ux_docs.md) | Review report for P7-T5 | | [REVIEW_tui_local_status_fallback.md](P7-T4_Add_direct_local-status_fallback_for_TUI_when_dashboard_API_is_unavailable/REVIEW_tui_local_status_fallback.md) | Review report for P7-T4 | @@ -640,3 +642,5 @@ | 2026-03-07 | P7-T3 | Archived REVIEW_dashboard_port_ownership_conflicts report | | 2026-03-10 | P2-T8 | Archived Gate_broker_tools_list_on_warmed_tool_catalog (PASS) | | 2026-03-10 | P2-T8 | Archived REVIEW_p2_t8_tools_catalog_gate report | +| 2026-03-10 | P1-T13 | Archived Document_stale_editable_install_version_mismatch_in_troubleshooting_guide (PASS) | +| 2026-03-10 | P1-T13 | Archived REVIEW_p1_t13_editable_install_troubleshooting report | diff --git a/SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md b/SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md new file mode 100644 index 0000000..bb7487f --- /dev/null +++ b/SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md @@ -0,0 +1,53 @@ +# PRD: P1-T13 — Document stale editable install version mismatch in troubleshooting guide + +## Status + +In Progress + +## Problem + +When a developer works in the local repository with `.venv` activated (or with `.venv/bin` on PATH), the `mcpbridge-wrapper` command resolves to the editable install inside `.venv`. The version metadata for that install is recorded in `.venv/lib/pythonX.Y/site-packages/mcpbridge_wrapper-{VERSION}.dist-info/` at the time `pip install -e .` was last run. + +If `pyproject.toml` is subsequently bumped to a new version (e.g. `0.4.1` → `0.4.2`) without re-running `pip install -e .`, the dist-info still reports the old version. As a result: + +- `mcpbridge-wrapper --doctor` shows `Package Version: 0.4.1` +- A broker daemon started via `uvx --from mcpbridge-wrapper` (which fetches fresh from PyPI) writes version `0.4.2` to `broker.version` +- `--doctor` detects a "version mismatch" and prompts the user to restart the broker +- The user is confused: they just released `0.4.2`, but their own dev environment reports `0.4.1` + +This is a pure developer environment issue — end users on `uvx` are never affected — but it can trap contributors and maintainers who have the repo `.venv` active in their shell. + +## Deliverables + +1. **`docs/troubleshooting.md`** — new section under a "Development / Local Repository" heading (or appended to an existing relevant section) that: + - Names the symptom: `--doctor` reports a version mismatch between local binary (`0.4.N`) and broker (`0.4.N+1`) + - Explains the root cause: stale `dist-info` from an old `pip install -e .` after `pyproject.toml` was bumped + - Provides the one-line fix: `.venv/bin/pip install -e .` (or `pip install -e .` with venv active) + - Notes that `uvx` always fetches the latest PyPI release independently of the local `.venv` + +2. **`Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md`** — DocC mirror synced to match the new section. + +## Acceptance Criteria + +- [ ] `docs/troubleshooting.md` describes the symptom, root cause (stale editable dist-info), and the fix (`pip install -e .`) +- [ ] The entry explains that `uvx` fetches from PyPI independently of the `.venv` editable install +- [ ] DocC mirror updated to match +- [ ] `make doccheck-all` passes (mirrors in sync) + +## Out of Scope + +- No code changes — documentation only +- No changes to `--doctor` output format +- End-user (non-dev) scenarios are already covered by existing version-mismatch entries + +## Dependencies + +None + +## Risk + +Low — documentation-only change. + +--- +**Archived:** 2026-03-10 +**Verdict:** PASS diff --git a/SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/P1-T13_Validation_Report.md b/SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/P1-T13_Validation_Report.md new file mode 100644 index 0000000..ddd3824 --- /dev/null +++ b/SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/P1-T13_Validation_Report.md @@ -0,0 +1,38 @@ +# Validation Report: P1-T13 + +## Task + +Document stale editable install version mismatch in troubleshooting guide + +## Date + +2026-03-10 + +## Changes Made + +### `docs/troubleshooting.md` + +Added new entry `### "Package Version" shows old release after version bump (development environment)` before the "Debug Mode" section. The entry covers: + +- Symptom: `--doctor` version mismatch with old package version from `.venv` dist-info +- Root cause: editable install dist-info is written at `pip install -e .` time, not at `pyproject.toml` bump time +- Clarification: `uvx` fetches from PyPI independently of `.venv` +- Fix: `.venv/bin/pip install -e .` to refresh dist-info + +### `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` + +Added matching section `## "Package Version" shows old release after version bump (development environment)` before the "Debug Mode" section. Content is condensed to DocC style (no client-specific sub-steps needed since this is a dev-only scenario). + +## Quality Gate Results + +| Gate | Result | +|------|--------| +| `pytest` | 902 passed, 5 skipped | +| `ruff check src/` | All checks passed | +| `mypy src/` | Success: no issues found in 20 source files | +| `pytest --cov` | 91.55% (≥ 90% required) ✅ | +| `make doccheck-all` | ✓ DocC documentation is in sync ✅ | + +## Verdict + +PASS diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_p1_t13_editable_install_troubleshooting.md b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t13_editable_install_troubleshooting.md new file mode 100644 index 0000000..973039a --- /dev/null +++ b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t13_editable_install_troubleshooting.md @@ -0,0 +1,39 @@ +## REVIEW REPORT — P1-T13 Editable Install Troubleshooting + +**Scope:** `origin/main..HEAD` +**Files:** 7 + +### Summary Verdict +- [x] Approve +- [ ] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues + +- None. + +### Secondary Issues + +- None. + +### Architectural Notes + +- The new troubleshooting entry is scoped to development environments only, so it clarifies a + maintainer-facing mismatch without adding noise to the end-user recovery paths. +- The DocC mirror remains aligned with `docs/troubleshooting.md`, preserving the repository's + documentation-sync contract and keeping `doccheck-all` meaningful. +- Archiving updates correctly close the task lifecycle in `Workplan`, `next.md`, and the archive + index, so the FLOW state now matches the branch contents. + +### Tests + +- `pytest` — PASS (`902 passed, 5 skipped, 2 warnings`) +- `ruff check src/` — PASS +- `mypy src/` — PASS +- `pytest --cov` — PASS (`91.55%`) +- `make doccheck-all` — PASS + +### Next Steps + +- No actionable review findings. FOLLOW-UP is skipped. diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 8d81c42..3a112cf 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -15,6 +15,7 @@ task only after a follow-up or new workplan entry is created. ## Recently Archived +- `2026-03-10` — `P1-T13` archived with verdict `PASS` - `2026-03-10` — `P2-T8` archived with verdict `PASS` - `2026-03-07` — `P8-T1` archived with verdict `PASS` - `2026-03-07` — `P7-T5` archived with verdict `PASS` diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 6bcf58e..6daa9fc 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -186,6 +186,22 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [x] `docs/troubleshooting.md` explains that inactive `mcpbridge-broker` entries in Xcode Agent Activity are usually historical sessions, not proof of multiple live brokers - [x] `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` mirrors the new guidance +#### ✅ P1-T13: Document stale editable install version mismatch in troubleshooting guide +- **Status:** ✅ Completed (2026-03-10) +- **Description:** When developing locally, the `.venv` editable install records the package version at install time in its `dist-info` directory. If `pyproject.toml` is bumped to a new version without re-running `pip install -e .`, the `mcpbridge-wrapper` command in the dev PATH still reports the old version. This causes `--doctor` to show a version mismatch between the running broker (started via `uvx`, which fetches the latest from PyPI) and the local binary. Document this scenario, its cause, and the fix (`pip install -e .` or `.venv/bin/pip install -e .`) in `docs/troubleshooting.md` so developers can self-diagnose without manual inspection of dist-info directories. +- **Priority:** P2 +- **Dependencies:** none +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - `docs/troubleshooting.md` — new entry under a "Development / Editable Install" section explaining the stale dist-info version mismatch and the fix + - `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` — DocC mirror synced + - `SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/` — archived PRD and validation report +- **Acceptance Criteria:** + - [x] `docs/troubleshooting.md` describes the symptom (`--doctor` reports version mismatch, package version is old), the root cause (stale editable dist-info after `pyproject.toml` bump), and the fix (`pip install -e .`) + - [x] The entry clarifies that `uvx` always fetches the latest PyPI release while the `.venv` editable install reflects the version at the time of `pip install -e .` + - [x] DocC mirror (`Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md`) is updated to match + - [x] `make doccheck-all` passes + ### Phase 2: Broker Robustness #### ✅ P2-T1: Replace --broker-spawn/--broker-connect with single --broker flag diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index 050f300..fb8e045 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -623,6 +623,42 @@ PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/b 2. Verify the wrapper process is running 3. Restart the MCP client connection +## "Package Version" shows old release after version bump (development environment) + +**Symptom:** You bumped `pyproject.toml` to a new version (for example `0.4.2`) and released to +PyPI, but `--doctor` still reports the old version for the local binary: + +``` +Python Runtime +- Package Version: 0.4.1 ← old version from .venv dist-info +... +Local Broker State +- Recorded Daemon Version: 0.4.2 ← broker started via uvx, fetched latest from PyPI +- Version Mismatch: yes (package 0.4.1) +``` + +**Cause:** The `mcpbridge-wrapper` command resolves to the editable install inside the repository +`.venv`. Package version metadata is stored in +`.venv/lib/pythonX.Y/site-packages/mcpbridge_wrapper-{VERSION}.dist-info/` and is written only +when `pip install -e .` runs. Bumping `pyproject.toml` alone does not update the dist-info. + +Meanwhile `uvx --from mcpbridge-wrapper` always fetches the latest published release from PyPI +independently of your local `.venv`, so the broker daemon writes the new version to +`broker.version`. The mismatch is an artifact of the dev environment, not a real compatibility +problem. End users running `uvx` are never affected. + +**Fix:** + +```bash +# From the repository root, reinstall the editable package to refresh dist-info +.venv/bin/pip install -e . + +# Verify the version now matches +mcpbridge-wrapper --doctor | grep "Package Version" +``` + +--- + ## Debug Mode To see what's happening under the hood: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e2f0c08..67d2a36 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -689,6 +689,54 @@ PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/b 4. Run one MCP request and confirm direct mode is active (no broker file recreation). +### "Package Version" shows old release after version bump (development environment) + +**Symptom:** You bumped `pyproject.toml` to a new version (for example `0.4.2`) and released to +PyPI, but `--doctor` still reports the old version for the local binary: + +``` +Python Runtime +- Package Version: 0.4.1 ← old version from .venv dist-info +... +Local Broker State +- Recorded Daemon Version: 0.4.2 ← broker started via uvx, fetched latest from PyPI +- Version Mismatch: yes (package 0.4.1) +``` + +**Cause:** The `mcpbridge-wrapper` command resolves to the editable install inside your repository +`.venv`. Package version metadata is stored in +`.venv/lib/pythonX.Y/site-packages/mcpbridge_wrapper-{VERSION}.dist-info/` and is written only +when `pip install -e .` runs. Bumping `pyproject.toml` alone does not update the dist-info — so +the installed binary still reports the version from the last `pip install -e .` invocation. + +Meanwhile `uvx --from mcpbridge-wrapper` always fetches the latest published release from PyPI +independently of your local `.venv`, so the broker daemon it starts writes the new version to +`broker.version`. The mismatch is an artifact of the dev environment, not a real compatibility +problem. + +**Affected:** Repository contributors and maintainers with `.venv/bin` on their `PATH` or with +the venv activated. End users running `uvx` are never affected. + +**Fix:** + +```bash +# From the repository root, reinstall the editable package to refresh dist-info +.venv/bin/pip install -e . + +# Verify the version now matches +mcpbridge-wrapper --doctor | grep "Package Version" +``` + +Or, if you have the venv activated: + +```bash +pip install -e . +``` + +After reinstalling, `--doctor` should show matching versions and no mismatch. + +--- + ## Debug Mode For verbose output, check the stderr stream: