devcoach 0.3.6__tar.gz → 0.3.8__tar.gz

{devcoach-0.3.6 → devcoach-0.3.8}/.github/workflows/ci.yml

@@ -117,7 +117,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@v6
         with:
@@ -149,14 +149,47 @@ jobs:
           path: dist/
           retention-days: 7
 
+  # ── Coverage comment on PR ──────────────────────────────────────────────
+  # Posts (and updates) a coverage summary comment on every PR push.
+  # Reads the .coverage file generated by pytest-cov — no extra deps needed.
+  coverage:
+    name: Coverage comment
+    needs: [bump]
+    if: >
+      github.event_name == 'pull_request'
+      && (needs.bump.result == 'success' || needs.bump.result == 'skipped')
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+      - run: uv sync --group dev
+      - name: Run tests with coverage
+        run: uv run pytest tests/ --cov=src/devcoach --cov-report=xml
+      - uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ github.token }}
+          MINIMUM_GREEN: 90
+          MINIMUM_ORANGE: 80
+
   # ── SonarCloud scan + quality gate ─────────────────────────────────────
-  # CI-based analysis: feeds coverage.xml to SonarCloud and blocks PR merge
-  # if the quality gate fails. Requires Automatic Analysis to be DISABLED on
-  # sonarcloud.io (Administration → Analysis Method).
+  # CI-based analysis: feeds coverage.xml to SonarCloud.
+  # Skipped on pull_request events — SONAR_TOKEN is not available to PR
+  # workflows (GitHub restricts secret access). Runs on main / tags / dispatch
+  # where the token is available.
+  # Requires Automatic Analysis to be DISABLED on sonarcloud.io
+  # (Administration → Analysis Method).
   sonar:
     name: SonarCloud scan
     needs: [bump, test]
-    if: always() && (needs.bump.result == 'success' || needs.bump.result == 'skipped') && needs.test.result == 'success'
+    if: >
+      always()
+      && github.event_name != 'pull_request'
+      && (needs.bump.result == 'success' || needs.bump.result == 'skipped')
+      && needs.test.result == 'success'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -169,12 +202,7 @@ jobs:
       - run: uv sync --group dev
       - name: Run tests with coverage
         run: uv run pytest tests/ -v --tb=short --cov=src/devcoach --cov-report=xml
-      - uses: sonarsource/sonarqube-scan-action@v6
-        env:
-          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-      - uses: sonarsource/sonarqube-quality-gate-action@v1
-        if: github.event_name == 'pull_request'
-        timeout-minutes: 5
+      - uses: sonarsource/sonarqube-scan-action@v7
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
 
@@ -198,12 +226,12 @@ jobs:
           python-version: "3.12"
       - run: uv sync --group docs
       - run: uv run mkdocs build
-      - uses: actions/upload-pages-artifact@v3
+      - uses: actions/upload-pages-artifact@v5
         with:
           path: site/
       - name: Deploy to GitHub Pages
         id: deploy
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5
 
   # ── Publish ─────────────────────────────────────────────────────────────
   # Runs when a tag is present: either created by the bump job (workflow_dispatch)

{devcoach-0.3.6 → devcoach-0.3.8}/.github/workflows/ruff-autofix.yml

@@ -30,7 +30,7 @@ jobs:
         run: uv run ruff format src/ tests/
 
       - name: Open PR if there are changes
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@v8
         with:
           commit-message: "style: apply ruff auto-fixes"
           title: "style: ruff auto-fix"

{devcoach-0.3.6 → devcoach-0.3.8}/CLAUDE.md

@@ -9,7 +9,7 @@ based on the user's knowledge map, the rate limit, and what has already been tau
 
 Repo: https://github.com/UltimaPhoenix/dev-coach
 PyPI package name: `devcoach`
-End-user command: `uvx devcoach`
+End-user command: `uvx devcoach` (CLI) / `uvx devcoach mcp` (MCP server)
 
 ---
 
@@ -240,7 +240,7 @@ npx @modelcontextprotocol/inspector devcoach
   "mcpServers": {
     "devcoach": {
       "command": "uvx",
-      "args": ["devcoach"]
+      "args": ["devcoach", "mcp"]
     }
   }
 }
@@ -252,7 +252,8 @@ npx @modelcontextprotocol/inspector devcoach
 
 - Follow **Uncle Bob's Clean Code** principles
 - Follow **PEP** standards
-- Linting and formatting enforced by **ruff** — run `uv run ruff check src/ tests/` and `uv run ruff format src/ tests/` before committing
+- Linting and formatting enforced by **ruff** — run `uv run ruff check src/ tests/` and `uv run ruff format src/ tests/` before committing. **All ruff checks must pass before committing.**
+- Test coverage must stay **at or above 80%** — run `uv run pytest --cov=src/devcoach --cov-fail-under=80` to verify. Do not merge code that drops total coverage below this threshold.
 - No external dependencies beyond `fastmcp` and `pydantic`
 - `db.py` exposes only pure functions — no business logic
 - `coach.py` never imports from `server.py` (one-way dependency)

{devcoach-0.3.6 → devcoach-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devcoach
-Version: 0.3.6
+Version: 0.3.8
 Summary: A local MCP server that acts as a progressive technical coach for Claude Code and Claude Desktop
 Project-URL: Homepage, https://github.com/UltimaPhoenix/dev-coach
 Project-URL: Repository, https://github.com/UltimaPhoenix/dev-coach
@@ -216,12 +216,11 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Education
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Requires-Dist: fastapi>=0.110
 Requires-Dist: fastmcp>=2.0
 Requires-Dist: jinja2>=3.1
@@ -233,7 +232,7 @@ Description-Content-Type: text/markdown
 # devcoach
 
 [![PyPI](https://img.shields.io/github/v/release/UltimaPhoenix/dev-coach?label=PyPI)](https://pypi.org/project/devcoach/)
-[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/devcoach/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://pypi.org/project/devcoach/)
 [![CI](https://github.com/UltimaPhoenix/dev-coach/actions/workflows/ci.yml/badge.svg)](https://github.com/UltimaPhoenix/dev-coach/actions/workflows/ci.yml)
 [![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=UltimaPhoenix_dev-coach&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=UltimaPhoenix_dev-coach)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=UltimaPhoenix_dev-coach&metric=coverage)](https://sonarcloud.io/summary/new_code?id=UltimaPhoenix_dev-coach)
@@ -259,9 +258,9 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 
 ## Screenshots
 
-| Knowledge map | Lesson history | Settings |
-|:---:|:---:|:---:|
-| ![Knowledge map](docs/screenshots/knowledge-map-light.png) | ![Lessons](docs/screenshots/lessons-dark.png) | ![Settings](docs/screenshots/settings-dark.png) |
+|                       Knowledge map                       | Lesson history | Settings |
+|:---------------------------------------------------------:|:---:|:---:|
+| ![Knowledge map](docs/screenshots/knowledge-map-dark.png) | ![Lessons](docs/screenshots/lessons-dark.png) | ![Settings](docs/screenshots/settings-dark.png) |
 
 ---
 
@@ -270,7 +269,7 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 ### Recommended — no permanent install needed
 
 ```bash
-uvx devcoach
+uvx devcoach mcp   # starts the MCP server directly
 ```
 
 ### Permanent install
@@ -287,7 +286,7 @@ devcoach install
 
 Restart Claude Code or Claude Desktop after installing.
 
-> **Requirements:** [uv](https://docs.astral.sh/uv/) · Python 3.11+ · Claude Code or Claude Desktop
+> **Requirements:** [uv](https://docs.astral.sh/uv/) · Python 3.12+ · Claude Code or Claude Desktop
 
 ---
 
@@ -322,7 +321,7 @@ Claude: [does the work]
 
 **Structured concurrency with asyncio.TaskGroup**
 
-TaskGroup (Python 3.11+) is the modern replacement for bare gather() calls.
+TaskGroup (Python 3.12+) is the modern replacement for bare gather() calls.
 Unlike gather(), it cancels sibling tasks automatically when one raises...
 ```
 
@@ -341,13 +340,16 @@ devcoach feedback lesson-python-taskgroup-001 dont_know # need to revisit —
 
 | Command | Description |
 |---------|-------------|
+| `devcoach` | Show all available commands |
+| `devcoach mcp` | Start the MCP server (stdio) for Claude Code / Claude Desktop |
 | `devcoach setup` | Run the onboarding wizard in the terminal |
 | `devcoach install` | Register with Claude Code / Claude Desktop |
 | `devcoach profile` | Show your knowledge map with confidence bars |
 | `devcoach stats` | Overview: lesson counts, weakest/strongest topics |
 | `devcoach lessons` | Browse lesson history with filters |
 | `devcoach lesson <id>` | Show a single lesson in full |
-| `devcoach star <id>` | Toggle starred flag |
+| `devcoach star <id>` | Mark a lesson as starred (favourite) |
+| `devcoach unstar <id>` | Remove the starred mark from a lesson |
 | `devcoach feedback <id> <know\|dont_know\|clear>` | Record comprehension |
 | `devcoach set max_per_day <n>` | Max lessons in a 24-hour window (default 2) |
 | `devcoach set min_gap_minutes <n>` | Minimum minutes between lessons (default 240) |
@@ -387,7 +389,7 @@ devcoach implements the [MCP 2025-11-25 spec](https://modelcontextprotocol.io/sp
     "devcoach": {
       "type": "stdio",
       "command": "uvx",
-      "args": ["devcoach"]
+      "args": ["devcoach", "mcp"]
     }
   }
 }
@@ -429,7 +431,7 @@ git tag v1.2.3
 git push origin v1.2.3
 ```
 
-The pipeline will lint, test across Python 3.11–3.13, build, publish to PyPI via OIDC Trusted Publishing, and create a GitHub Release automatically.
+The pipeline will lint, test across Python 3.12–3.13, build, publish to PyPI via OIDC Trusted Publishing, and create a GitHub Release automatically.
 
 > **First-time PyPI setup:** configure a Trusted Publisher on PyPI for `UltimaPhoenix/dev-coach` (environment: `pypi`, workflow: `ci.yml`). No API token required after that.
 

{devcoach-0.3.6 → devcoach-0.3.8}/README.md

@@ -1,7 +1,7 @@
 # devcoach
 
 [![PyPI](https://img.shields.io/github/v/release/UltimaPhoenix/dev-coach?label=PyPI)](https://pypi.org/project/devcoach/)
-[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/devcoach/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://pypi.org/project/devcoach/)
 [![CI](https://github.com/UltimaPhoenix/dev-coach/actions/workflows/ci.yml/badge.svg)](https://github.com/UltimaPhoenix/dev-coach/actions/workflows/ci.yml)
 [![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=UltimaPhoenix_dev-coach&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=UltimaPhoenix_dev-coach)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=UltimaPhoenix_dev-coach&metric=coverage)](https://sonarcloud.io/summary/new_code?id=UltimaPhoenix_dev-coach)
@@ -27,9 +27,9 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 
 ## Screenshots
 
-| Knowledge map | Lesson history | Settings |
-|:---:|:---:|:---:|
-| ![Knowledge map](docs/screenshots/knowledge-map-light.png) | ![Lessons](docs/screenshots/lessons-dark.png) | ![Settings](docs/screenshots/settings-dark.png) |
+|                       Knowledge map                       | Lesson history | Settings |
+|:---------------------------------------------------------:|:---:|:---:|
+| ![Knowledge map](docs/screenshots/knowledge-map-dark.png) | ![Lessons](docs/screenshots/lessons-dark.png) | ![Settings](docs/screenshots/settings-dark.png) |
 
 ---
 
@@ -38,7 +38,7 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 ### Recommended — no permanent install needed
 
 ```bash
-uvx devcoach
+uvx devcoach mcp   # starts the MCP server directly
 ```
 
 ### Permanent install
@@ -55,7 +55,7 @@ devcoach install
 
 Restart Claude Code or Claude Desktop after installing.
 
-> **Requirements:** [uv](https://docs.astral.sh/uv/) · Python 3.11+ · Claude Code or Claude Desktop
+> **Requirements:** [uv](https://docs.astral.sh/uv/) · Python 3.12+ · Claude Code or Claude Desktop
 
 ---
 
@@ -90,7 +90,7 @@ Claude: [does the work]
 
 **Structured concurrency with asyncio.TaskGroup**
 
-TaskGroup (Python 3.11+) is the modern replacement for bare gather() calls.
+TaskGroup (Python 3.12+) is the modern replacement for bare gather() calls.
 Unlike gather(), it cancels sibling tasks automatically when one raises...
 ```
 
@@ -109,13 +109,16 @@ devcoach feedback lesson-python-taskgroup-001 dont_know # need to revisit —
 
 | Command | Description |
 |---------|-------------|
+| `devcoach` | Show all available commands |
+| `devcoach mcp` | Start the MCP server (stdio) for Claude Code / Claude Desktop |
 | `devcoach setup` | Run the onboarding wizard in the terminal |
 | `devcoach install` | Register with Claude Code / Claude Desktop |
 | `devcoach profile` | Show your knowledge map with confidence bars |
 | `devcoach stats` | Overview: lesson counts, weakest/strongest topics |
 | `devcoach lessons` | Browse lesson history with filters |
 | `devcoach lesson <id>` | Show a single lesson in full |
-| `devcoach star <id>` | Toggle starred flag |
+| `devcoach star <id>` | Mark a lesson as starred (favourite) |
+| `devcoach unstar <id>` | Remove the starred mark from a lesson |
 | `devcoach feedback <id> <know\|dont_know\|clear>` | Record comprehension |
 | `devcoach set max_per_day <n>` | Max lessons in a 24-hour window (default 2) |
 | `devcoach set min_gap_minutes <n>` | Minimum minutes between lessons (default 240) |
@@ -155,7 +158,7 @@ devcoach implements the [MCP 2025-11-25 spec](https://modelcontextprotocol.io/sp
     "devcoach": {
       "type": "stdio",
       "command": "uvx",
-      "args": ["devcoach"]
+      "args": ["devcoach", "mcp"]
     }
   }
 }
@@ -197,7 +200,7 @@ git tag v1.2.3
 git push origin v1.2.3
 ```
 
-The pipeline will lint, test across Python 3.11–3.13, build, publish to PyPI via OIDC Trusted Publishing, and create a GitHub Release automatically.
+The pipeline will lint, test across Python 3.12–3.13, build, publish to PyPI via OIDC Trusted Publishing, and create a GitHub Release automatically.
 
 > **First-time PyPI setup:** configure a Trusted Publisher on PyPI for `UltimaPhoenix/dev-coach` (environment: `pypi`, workflow: `ci.yml`). No API token required after that.
 

{devcoach-0.3.6 → devcoach-0.3.8}/docs/cli.md

@@ -1,15 +1,38 @@
 # CLI reference
 
-## Global
+## Overview
+
+Running `devcoach` with no arguments prints a help panel listing every available command:
 
 ```
-devcoach <command> [options]
+devcoach
 ```
 
 All commands operate on `~/.devcoach/coaching.db`. No network access required.
 
 ---
 
+## MCP server
+
+### `devcoach mcp`
+
+Start the stdio MCP server for Claude Code or Claude Desktop. This is what you put in your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "devcoach": {
+      "command": "uvx",
+      "args": ["devcoach", "mcp"]
+    }
+  }
+}
+```
+
+---
+
+---
+
 ## Knowledge map
 
 ### `devcoach profile`
@@ -117,13 +140,24 @@ devcoach lesson lesson-python-generators-001
 
 ### `devcoach star <id>`
 
-Toggle the starred (favourite) flag on a lesson.
+Mark a lesson as starred (favourite).
 
 ```bash
 devcoach star lesson-python-generators-001
 # → Lesson lesson-python-generators-001 → ★ starred
 ```
 
+### `devcoach unstar <id>`
+
+Remove the starred mark from a lesson.
+
+```bash
+devcoach unstar lesson-python-generators-001
+# → Lesson lesson-python-generators-001 → ☆ unstarred
+```
+
+Both commands are idempotent — calling them when the lesson is already in the target state is safe.
+
 ### `devcoach feedback <id> <value>`
 
 Record whether you understood a lesson. Adjusts knowledge confidence.
@@ -191,7 +225,7 @@ Followed by optional group assignment and rate-limit settings.
 
 ### `devcoach install`
 
-Register the devcoach MCP server in Claude's config files.
+Register the devcoach MCP server (`devcoach mcp`) in Claude's config files.
 
 ```bash
 devcoach install                  # both Claude Code + Claude Desktop

{devcoach-0.3.6 → devcoach-0.3.8}/docs/getting-started.md

@@ -3,25 +3,35 @@
 ## Prerequisites
 
 - [uv](https://docs.astral.sh/uv/) (recommended) or pip
-- Python 3.11+
+- Python 3.12+
 - Claude Code or Claude Desktop
 
 ---
 
 ## 1. Install
 
-### One-time run (no permanent install)
+devcoach is published on [PyPI](https://pypi.org/project/devcoach/) and can be installed with any Python package manager.
+
+### One-time run — no install needed
 
 ```bash
-uvx devcoach
+uvx devcoach mcp
 ```
 
-### Permanent install
+`uvx` fetches the latest release from PyPI and runs it in an isolated environment. Nothing is left behind.
+
+### Permanent install with uv (recommended)
 
 ```bash
 uv tool install devcoach
 ```
 
+### Permanent install with pip
+
+```bash
+pip install devcoach
+```
+
 ---
 
 ## 2. Register with Claude

{devcoach-0.3.6 → devcoach-0.3.8}/docs/index.md

@@ -41,7 +41,7 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
     ![Settings – dark theme](screenshots/settings-dark.png)
 
 === "Light"
-    ![Settings – light theme](screenshots/settings-dark.png)
+    ![Settings – light theme](screenshots/settings-light.png)
 
 ---
 

{devcoach-0.3.6 → devcoach-0.3.8}/docs/mcp-server.md

@@ -14,12 +14,15 @@ The server exposes **tools** (mutations), **resources** (read-only data), and a
     "devcoach": {
       "type": "stdio",
       "command": "uvx",
-      "args": ["devcoach"]
+      "args": ["devcoach", "mcp"]
     }
   }
 }
 ```
 
+!!! note
+    The `mcp` subcommand is required. Running `devcoach` without it launches the CLI instead of the MCP server.
+
 ---
 
 ## Tools (mutations)
@@ -52,7 +55,7 @@ Save a delivered lesson to the coaching log. Git metadata is auto-detected from
 | `folder` | string | Absolute path to cwd |
 | `repository_platform` | `"github" \| "gitlab" \| "bitbucket" \| "local"` | VCS platform |
 
-Returns `"ok"` on success, `"error: <message>"` on failure.
+Returns the saved `Lesson` object with all resolved fields (including any auto-filled git context).
 
 ---
 
@@ -112,12 +115,14 @@ All parameters are optional and combinable. Returns `Lesson[]`.
 
 ### `star_lesson`
 
-Toggle the starred flag. Returns `"starred"` or `"unstarred"`.
+Set the starred (favourite) flag to an explicit value. Idempotent — calling with the same value twice is safe.
 
 ```json
-{ "lesson_id": "lesson-python-generators-001" }
+{ "lesson_id": "lesson-python-generators-001", "starred": true }
 ```
 
+Returns the new `starred` state as a boolean.
+
 ---
 
 ### `submit_feedback`

{devcoach-0.3.6 → devcoach-0.3.8}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "devcoach"
-version = "0.3.6"
+version = "0.3.8"
 description = "A local MCP server that acts as a progressive technical coach for Claude Code and Claude Desktop"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.12"
 license = { file = "LICENSE" }
 authors = [
     { name = "UltimaPhoenix", email = "2079222+UltimaPhoenix@users.noreply.github.com" },
@@ -15,7 +15,6 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Libraries :: Python Modules",
@@ -60,7 +59,7 @@ docs = [
 
 [tool.ruff]
 line-length = 100
-target-version = "py311"
+target-version = "py312"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP"]

{devcoach-0.3.6 → devcoach-0.3.8}/sonar-project.properties

@@ -2,10 +2,10 @@ sonar.projectKey=UltimaPhoenix_dev-coach
 sonar.organization=ultimaphoenix
 
 sonar.projectName=devcoach
-sonar.projectVersion=0.3.6
+sonar.projectVersion=0.3.8
 
 sonar.sources=src
 sonar.tests=tests
-sonar.python.version=3.11
+sonar.python.version=3.12
 
 sonar.python.coverage.reportPaths=coverage.xml