diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..416d11c --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,20 @@ +# Roadmap + +## Current + +- **v0.1.4** — shipped (pre-PyPI; installed via `uvx --from git+…`) +- **v0.1.5** — in progress. Five coordinated workstreams: positioning lockdown ("canonical Python stdlib oracle for AI coding agents — always free, always MIT, token-frugal"); first PyPI publish via Trusted Publishing; GitHub repo rename to `python-stdlib-mcp` (PyPI package name stays `python-docs-mcp-server`); benchmark harness against competing docs MCPs; coordinated launch post on a personal blog, dev.to, and Show HN. + +## Backlog (post-v0.1.5) + +| Phase | Title | Tool surface | Issue | +|-------|-------|--------------|-------| +| 09 | `compare_versions(symbol, v1, v2)` | New MCP tool | #TBD-link-after-PR-merges | +| 10 | `whatsnew_for_version(version)` | New MCP tool | #TBD-link-after-PR-merges | +| 11 | `detect_python_version` v2 (venv-aware) | Existing tool enhancement | #TBD-link-after-PR-merges | + +These are planned, not committed. Phase CONTEXTs at [`phases/09-compare-versions/`](phases/09-compare-versions/09-CONTEXT.md), [`phases/10-whatsnew/`](phases/10-whatsnew/10-CONTEXT.md), [`phases/11-detect-venv/`](phases/11-detect-venv/11-CONTEXT.md). Implementation kickoff requires `/gsd-plan-phase 0X`. + +## Historical + +Pre-2026-05-14 GSD workflow artifacts (phases 1–8 for v0.1.0) live in maintainers' local worktrees and are intentionally not tracked in this repo — they remain accessible to those who ran the original GSD workflow locally but are not load-bearing for current implementation work. With v0.1.5 the `.planning/` directory becomes a tracked, forward-facing surface for new phase CONTEXTs and roadmap entries. diff --git a/.planning/phases/09-compare-versions/09-CONTEXT.md b/.planning/phases/09-compare-versions/09-CONTEXT.md new file mode 100644 index 0000000..5c27ef6 --- /dev/null +++ b/.planning/phases/09-compare-versions/09-CONTEXT.md @@ -0,0 +1,40 @@ +# Phase 09 — compare_versions(symbol, v1, v2) + +**Status:** Backlog (post-v0.1.5) +**Type:** New MCP tool + +## Goal + +Add an MCP tool `compare_versions(symbol, v1, v2)` that returns a structured diff of a stdlib symbol's signature, behavior, and docstring between two Python versions. + +## Depends on + +- v0.1.5 ships (PyPI debut + repo rename complete). +- Index supports the two versions being compared (handled by `build-index`). + +## Requirements + +- CMPR-01: Tool accepts `(symbol: str, v1: str, v2: str)`. Returns a structured diff: signature change, docstring delta, deprecation flag, see-also additions/removals. +- CMPR-02: Both versions must already be indexed; if not, tool returns an actionable error pointing at `build-index`. +- CMPR-03: Diff format is JSON-serializable and token-frugal — no full re-printing of unchanged paragraphs. + +## Success criteria + +1. `compare_versions("asyncio.TaskGroup", "3.10", "3.11")` returns a clear, machine-readable diff showing the symbol was newly introduced in 3.11 (e.g. an `added` or `new_in` marker, not just a delta of existing fields). +2. Comparing identical versions returns an empty diff with an explicit "no change" marker. +3. Missing-version cases return an actionable error with the indexed-version list. +4. Token cost of a typical diff is under 300 tokens (vs ~1500 for fetching both full doc pages). +5. Integration test in `tests/test_compare_versions.py` exercises 3 representative symbols (one changed, one unchanged, one missing). + +## Plans + +TBD — run `/gsd-plan-phase 09` after this issue is prioritized. + +## UI hint + +No UI surface; pure MCP tool. + +## Out of scope + +- Cross-language diffs (Python stdlib only). +- Non-symbol diffs (module-level changes belong in phase 10). diff --git a/.planning/phases/10-whatsnew/10-CONTEXT.md b/.planning/phases/10-whatsnew/10-CONTEXT.md new file mode 100644 index 0000000..97429f6 --- /dev/null +++ b/.planning/phases/10-whatsnew/10-CONTEXT.md @@ -0,0 +1,40 @@ +# Phase 10 — whatsnew_for_version(version) + +**Status:** Backlog (post-v0.1.5) +**Type:** New MCP tool + +## Goal + +Return the official "What's New in Python ``" content as structured sections, scoped by topic — new modules, deprecations, removals, performance, syntax. The current alternative is for the agent to fetch a full HTML page; this tool returns just the requested sections. + +## Depends on + +- v0.1.5 ships. +- Ingestion already covers `whatsnew/.html` (verify during phase planning). + +## Requirements + +- WNEW-01: Tool signature: `whatsnew_for_version(version: str, kind: str | None = None, start_index: int = 0, max_sections: int = 20)`. `kind` filters to a single `kind` value (see WNEW-02); `start_index` + `max_sections` paginate the response. Returns `{ "sections": [{title, anchor, body, kind}], "next_start_index": int | None }`. +- WNEW-02: `kind` enum: `new_module | new_feature | deprecation | removal | performance | syntax | other`. +- WNEW-03: Each section's `body` is capped at ~2k tokens. If a single section exceeds the cap, truncate with a clear marker and a `get_docs` hint. Pagination via `start_index` / `next_start_index` round-trips. + +## Success criteria + +1. `whatsnew_for_version("3.12")` returns ≥10 sections, each with a non-empty body. +2. Each section has a stable anchor matching docs.python.org. +3. Filtering by `kind` is supported (`whatsnew_for_version("3.12", kind="deprecation")`). +4. Missing version returns the same actionable error pattern as `compare_versions`. +5. Integration test in `tests/test_whatsnew.py` covers two representative versions. + +## Plans + +TBD. + +## UI hint + +No UI surface; pure MCP tool. + +## Out of scope + +- Third-party "what's new" guides. +- Cross-version aggregation (use `compare_versions` instead). diff --git a/.planning/phases/11-detect-venv/11-CONTEXT.md b/.planning/phases/11-detect-venv/11-CONTEXT.md new file mode 100644 index 0000000..2b5291d --- /dev/null +++ b/.planning/phases/11-detect-venv/11-CONTEXT.md @@ -0,0 +1,43 @@ +# Phase 11 — detect_python_version v2 (venv-aware) + +**Status:** Backlog (post-v0.1.5) +**Type:** Enhancement of existing MCP tool + +## Goal + +Make `detect_python_version` venv-aware: report the Python version of the *active virtual environment* in the user's project, not just the value from `.python-version` or `python3 --version` on PATH. + +## Depends on + +- v0.1.5 ships. +- v1 implementation at `src/mcp_server_python_docs/detection.py` (current 3-step detection order: `.python-version` → `python3 --version` → `sys.version_info`). +- v1 has NO dedicated unit test file — backfill `tests/test_detection.py` as part of this phase. + +## Requirements + +- DETV2-01: Detect active venv via the `VIRTUAL_ENV` env var; if present, read `$VIRTUAL_ENV/pyvenv.cfg` and parse the `version = X.Y[.Z]` key (the standard key written by `python -m venv`). Fall back to `version_info` only if `version` is absent — some tools write that variant. +- DETV2-02: Detect `.venv/` or `venv/` directories in cwd or its ancestors (up to project root). +- DETV2-03: Detect `uv`'s `.venv` and `poetry`'s `.venv` patterns. +- DETV2-04: Preserve v1 fallback chain unchanged below the new venv checks. +- DETV2-05: Return `(major_minor, source)` tuple. **New v2 sources:** `"venv:VIRTUAL_ENV"`, `"venv:.venv"`. **Existing v1 sources (preserved unchanged, see `src/mcp_server_python_docs/detection.py`):** `".python-version file"`, `"python3 in PATH"`, `"server runtime"`. Total: 5 distinct source strings. + +## Success criteria + +1. Inside an activated venv (3.12) on a 3.13 host: returns `("3.12", "venv:VIRTUAL_ENV")`. +2. With no venv but `.python-version` present: returns `("X.Y", ".python-version file")` — v1 behavior preserved verbatim. +3. With nothing else available: returns `(sys-version, "server runtime")` — v1 fallback preserved verbatim. +4. Backfill: `tests/test_detection.py` covers all five `source` cases (2 new + 3 preserved). +5. No regression in v1 callers (`server.py` MCP tool wrapper signature unchanged; existing source strings unchanged). + +## Plans + +TBD. + +## UI hint + +No UI surface; pure MCP tool. + +## Out of scope + +- conda / mamba environments (separate phase if demand surfaces). +- Cross-platform venv path quirks beyond Unix + Windows (both must be tested). diff --git a/AGENTS.md b/AGENTS.md index 6cb220b..931782c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -83,15 +83,15 @@ Before calling work complete: ## Context Hygiene -Treat `.planning/` as archival project history, not live repo truth. - -Start with these files instead: - -- `README.md` -- `CONTRIBUTING.md` -- `.github/INTEGRATION-TEST.md` -- `tests/` - -The generated planning files may still be useful for maintainers who want the -old GSD workflow context, but they should not drive routine implementation -decisions. +`.planning/` mixes archival history with forward-facing phase CONTEXTs. + +- `.planning/ROADMAP.md` and `.planning/phases/0X-…/0X-CONTEXT.md` are live, + forward-looking specs — read these first when starting a new phase. +- Anything else in `.planning/` (especially content dated 2026-04 or earlier) + is archival history. It may help maintainers reconstruct prior context but + should not drive routine implementation decisions. +- For the source of truth about *what the code does today*, start with: + - `README.md` + - `CONTRIBUTING.md` + - `.github/INTEGRATION-TEST.md` + - `tests/`