devcoach 0.3.8__tar.gz → 0.3.9__tar.gz

devcoach-0.3.9/.github/scripts/export_backup.py

@@ -0,0 +1,138 @@
+"""Anonymize a devcoach backup zip for safe public sharing.
+
+Replacements applied to lessons.json:
+  - Absolute paths (/root/username/...)        → /home/user/...
+  - Repository owner prefix (owner/repo)       → developer/repo
+  - Commit hashes (full 40-char SHA-1)         → random 40-char hex
+
+Usage:
+    python .github/scripts/anonymize_backup.py <input.zip> [output.zip]
+
+If output.zip is omitted the anonymized file is written next to the input
+with "-anon" appended to the stem (e.g. devcoach-backup-anon.zip).
+"""
+
+import json
+import re
+import secrets
+import sys
+import zipfile
+from pathlib import Path
+
+
+SHA1_RE = re.compile(r"\b[0-9a-f]{40}\b", re.IGNORECASE)
+REPO_USER_RE = re.compile(r"^[^/\s]+/")
+
+ANON_REPO_PREFIX = "developer/"
+
+
+def _random_sha1() -> str:
+    return secrets.token_hex(20)
+
+
+def _anonymize_path(path: str) -> str:
+    """Replace username in any absolute path /root/username/... → /home/user/..."""
+    parts = path.split("/")
+    # Absolute path: ['', '<root>', '<username>', ...]
+    if len(parts) >= 3 and parts[0] == "" and parts[1] and parts[2]:
+        parts[1] = "home"
+        parts[2] = "user"
+    return "/".join(parts)
+
+
+def _has_personal_path(value: str) -> bool:
+    """True if value contains an absolute path whose username is not 'user'."""
+    parts = value.split("/")
+    return (
+        len(parts) >= 3
+        and parts[0] == ""
+        and parts[1] != ""
+        and parts[2] not in ("", "user")
+        and "/" in value[1:]  # at least one slash after the leading one
+    )
+
+
+def anonymize_lesson(lesson: dict, original_hashes: set[str]) -> dict:
+    out = dict(lesson)
+
+    if out.get("folder"):
+        out["folder"] = _anonymize_path(out["folder"])
+
+    if out.get("repository"):
+        out["repository"] = REPO_USER_RE.sub(ANON_REPO_PREFIX, out["repository"])
+
+    if out.get("commit_hash"):
+        original_hashes.add(out["commit_hash"].lower())
+        out["commit_hash"] = _random_sha1()
+
+    if out.get("task_context"):
+        ctx = out["task_context"]
+
+        def _replace_hash(m: re.Match) -> str:
+            original_hashes.add(m.group().lower())
+            return _random_sha1()
+
+        ctx = SHA1_RE.sub(_replace_hash, ctx)
+        tokens = ctx.split()
+        ctx = " ".join(_anonymize_path(t) if _has_personal_path(t) else t for t in tokens)
+        out["task_context"] = ctx
+
+    return out
+
+
+def anonymize_zip(src: Path, dst: Path) -> None:
+    original_hashes: set[str] = set()
+
+    with zipfile.ZipFile(src) as zin, zipfile.ZipFile(dst, "w", zipfile.ZIP_DEFLATED) as zout:
+        for name in zin.namelist():
+            if name == "learning-state.md":
+                continue  # personal coaching narrative — excluded from anon export
+
+            raw = zin.read(name)
+
+            if name == "lessons.json":
+                lessons = json.loads(raw.decode())
+                lessons = [anonymize_lesson(l, original_hashes) for l in lessons]
+                raw = json.dumps(lessons, indent=2, ensure_ascii=False).encode()
+
+            zout.writestr(name, raw)
+
+    print(f"Anonymized backup written to: {dst}")
+    _verify(dst, original_hashes)
+
+
+def _verify(path: Path, original_hashes: set[str]) -> None:
+    with zipfile.ZipFile(path) as z:
+        lessons = json.loads(z.read("lessons.json").decode())
+    issues: list[str] = []
+    for lesson in lessons:
+        for field in ("folder", "repository", "commit_hash", "task_context"):
+            val = lesson.get(field) or ""
+            if _has_personal_path(val):
+                issues.append(f"  {lesson['id']}.{field}: personal path still present")
+            for match in SHA1_RE.finditer(val):
+                if match.group().lower() in original_hashes:
+                    issues.append(f"  {lesson['id']}.{field}: original SHA-1 hash still present")
+    if issues:
+        print("Verification warnings:")
+        for w in issues:
+            print(w)
+    else:
+        print(f"Verification passed ({len(lessons)} lessons, no personal data detected).")
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        sys.exit(f"Usage: python {sys.argv[0]} <input.zip> [output.zip]")
+
+    src = Path(sys.argv[1])
+    if not src.exists():
+        sys.exit(f"File not found: {src}")
+
+    dst = Path(sys.argv[2]) if len(sys.argv) > 2 else src.with_stem(src.stem + "-anon")
+
+    anonymize_zip(src, dst)
+
+
+if __name__ == "__main__":
+    main()

{devcoach-0.3.8 → devcoach-0.3.9}/.github/scripts/take_screenshots.py

@@ -27,6 +27,14 @@ PAGES = [
     ("settings", "/settings"),
 ]
 
+LESSON_PAGES = [
+    ("lesson-docker-layer-cache", "/lessons/lesson-docker-layer-cache-001"),
+    ("lesson-postgresql-explain-analyze", "/lessons/lesson-postgresql-explain-analyze-001"),
+    ("lesson-git-interactive-rebase", "/lessons/lesson-git-interactive-rebase-001"),
+    ("lesson-ci-cd-pipeline-stages", "/lessons/lesson-ci-cd-pipeline-stages-001"),
+    ("lesson-redis-cache-stampede", "/lessons/lesson-redis-cache-stampede-001"),
+]
+
 def restore_db() -> None:
     result = subprocess.run(
         ["devcoach", "restore", str(BACKUP_ZIP)],
@@ -55,25 +63,16 @@ def take_screenshots(server_proc: subprocess.Popen) -> None:
     with sync_playwright() as pw:
         browser = pw.chromium.launch()
 
-        ctx = browser.new_context(viewport=VIEWPORT, color_scheme="light")
-        page = ctx.new_page()
-        for name, path in PAGES:
-            page.goto(f"{BASE_URL}{path}")
-            page.wait_for_load_state("networkidle")
-            out = SCREENSHOTS_DIR / f"{name}-light.png"
-            page.screenshot(path=str(out))
-            print(f"  saved {out}")
-        ctx.close()
-
-        ctx = browser.new_context(viewport=VIEWPORT, color_scheme="dark")
-        page = ctx.new_page()
-        for name, path in PAGES:
-            page.goto(f"{BASE_URL}{path}")
-            page.wait_for_load_state("networkidle")
-            out = SCREENSHOTS_DIR / f"{name}-dark.png"
-            page.screenshot(path=str(out))
-            print(f"  saved {out}")
-        ctx.close()
+        for scheme in ("light", "dark"):
+            ctx = browser.new_context(viewport=VIEWPORT, color_scheme=scheme)
+            page = ctx.new_page()
+            for name, path in PAGES + LESSON_PAGES:
+                page.goto(f"{BASE_URL}{path}")
+                page.wait_for_load_state("networkidle")
+                out = SCREENSHOTS_DIR / f"{name}-{scheme}.png"
+                page.screenshot(path=str(out))
+                print(f"  saved {out}")
+            ctx.close()
 
         browser.close()
 

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

@@ -202,7 +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@v7
+      - uses: sonarsource/sonarqube-scan-action@v8
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
 

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

@@ -7,7 +7,6 @@ on:
 
 permissions:
   contents: write
-  pull-requests: write
 
 jobs:
   autofix:
@@ -29,16 +28,12 @@ jobs:
       - name: Run ruff format
         run: uv run ruff format src/ tests/
 
-      - name: Open PR if there are changes
-        uses: peter-evans/create-pull-request@v8
-        with:
-          commit-message: "style: apply ruff auto-fixes"
-          title: "style: ruff auto-fix"
-          body: |
-            Automated style fixes applied by `ruff check --fix` and `ruff format`.
-
-            This PR was opened automatically by the **Ruff auto-fix** workflow.
-            Review the diff, then merge or close.
-          branch: ruff/autofix
-          delete-branch: true
-          labels: style
+      - name: Commit and push if there are changes
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git diff --staged --quiet && echo "No changes." || (
+            git commit -m "style: apply ruff auto-fixes [skip ci]" &&
+            git push
+          )

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devcoach
-Version: 0.3.8
+Version: 0.3.9
 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

devcoach-0.3.9/docs/how-it-works.md

@@ -0,0 +1,112 @@
+# How it works
+
+devcoach is a silent technical coach that hooks into every Claude response.
+The diagrams below show the three main flows: session startup, the coaching loop,
+and how a lesson topic is selected.
+
+---
+
+## Session startup
+
+At the start of each Claude session devcoach checks whether the user is set up,
+loads prior coaching context, and primes lesson selection before any task is done.
+
+```mermaid
+flowchart TD
+    A([Session starts]) --> B[Read devcoach://onboarding]
+    B --> C{needs_onboarding?}
+    C -- Yes --> D{Existing backup\nto restore?}
+    D -- Yes --> E[Restore backup\n→ mark onboarding done]
+    D -- No --> F[Detect stack\nautomatically or manually]
+    F --> G[Confirm topics + confidence\nPropose groups]
+    G --> H[complete_onboarding]
+    E & H --> I
+    C -- No --> I[Read ~/.devcoach/learning-state.md]
+    I --> J{Notebook\nnon-empty?}
+    J -- Yes --> K[Load patterns, hypotheses\nand recommended angles]
+    J -- No --> L[No prior context\nstart fresh]
+    K & L --> M([Ready to coach])
+```
+
+---
+
+## Coaching loop
+
+After every technical task Claude evaluates whether to deliver a lesson.
+The loop is silent when nothing is worth teaching or when the rate limit is reached.
+
+```mermaid
+flowchart TD
+    A([Technical task\ncompleted]) --> B[Read devcoach://rate-limit]
+    B --> C{Allowed?}
+    C -- No\nnormal task --> Z([Silent —\nno lesson])
+    C -- No\nexplicit request --> D
+    C -- Yes --> D[Read profile\ntaught topics\ncoaching notebook]
+    D --> E[Analyse task for\nteachable concepts]
+    E --> F[Select topic\nsee Lesson selection]
+    F --> G{Topic\nfound?}
+    G -- No --> Z
+    G -- Yes --> H[Compose lesson\ncalibrate depth per-topic]
+    H --> I[log_lesson to MCP]
+    I --> J([Lesson appears\nat end of response])
+    J --> K{User\nfeedback}
+    K -- ✅ know --> L{Confidence\nbelow level band?}
+    L -- Yes --> M[submit_feedback\nconfidence +1]
+    L -- No --> N[Skip — already calibrated]
+    K -- ❌ don't know --> O[submit_feedback\nconfidence −1]
+    K -- ⏭ skip --> P[No change]
+    M & N & O & P --> Q{New observation\nworth saving?}
+    Q -- Yes --> R[Write ~/.devcoach/\nlearning-state.md]
+    Q -- No --> S
+    R --> S([Loop ends])
+```
+
+---
+
+## Lesson selection
+
+When a teachable concept is found, devcoach picks the highest-priority angle
+and calibrates the lesson level to the **per-topic** confidence score — not an average.
+
+```mermaid
+flowchart TD
+    A([Concepts identified\nin current task]) --> B{Notebook flags\na follow-up angle\nrelevant to this task?}
+    B -- Yes --> P1["① Deliver notebook\nfollow-up"]
+
+    B -- No --> C{Pitfall on a\nprofile topic?}
+    C -- Yes --> P2["② Profile pitfall"]
+
+    C -- No --> D{Interesting pattern\non a profile topic?}
+    D -- Yes --> P3["③ Profile pattern"]
+
+    D -- No --> E{Off-profile concept\nprominent in task?}
+    E -- Yes --> P4["④ Off-profile pitfall"]
+
+    E -- No --> F{Profile topic with\nconfidence < 5?}
+    F -- Yes --> P5["⑤ Knowledge gap"]
+
+    F -- No --> G{Profile topic at\nconfidence 4–6?}
+    G -- Yes --> P6["⑥ Deep-dive"]
+
+    G -- No --> Z([Nothing to teach\n— stay silent])
+
+    P1 & P2 & P3 & P4 & P5 & P6 --> L[Check taught-topics\nno repeats]
+    L --> M{Already taught\nor confidence ≥ 10?}
+    M -- Already taught\nnot confidence 10 --> Z
+    M -- OK or\nconfidence = 10 --> N[Calibrate level\nper-topic confidence]
+    N --> O([Compose and\ndeliver lesson])
+```
+
+---
+
+## Depth calibration
+
+The lesson level is determined by the confidence score for the **specific topic being taught**,
+adjusted by observations in the coaching notebook.
+
+| Confidence | Level | Lesson angle |
+|---|---|---|
+| 0 – 3 | Junior | Introduce correct practice, explain from scratch, use analogies |
+| 4 – 6 | Mid | Explain the why, mention trade-offs and alternatives |
+| 7 – 9 | Senior | Edge cases, historical context, architectural implications |
+| 10 | Cutting-edge | Latest developments — ignores level floor and taught-topics filter |

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

@@ -8,12 +8,30 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 
 ## How it works
 
-| Step | What happens |
-|------|-------------|
-| You complete a task with Claude | Claude finishes the work as normal |
-| devcoach checks your knowledge map | Finds a topic where you have room to grow, related to what you just did |
-| A lesson appears at the end of the response | Calibrated to your level (junior / mid / senior), never repeated |
-| You mark it know / don't know | Confidence scores update, shaping future lessons |
+```mermaid
+sequenceDiagram
+    actor User
+    participant Claude as Claude (AI)
+    participant devcoach as devcoach (MCP)
+
+    User->>+Claude: Complete a technical task
+    Claude-->>User: Work completed normally
+
+    Claude->>devcoach: check rate-limit + profile + taught topics
+    devcoach-->>Claude: knowledge map · lesson history · coaching notebook
+
+    Claude->>Claude: select topic · calibrate depth · compose lesson
+
+    Claude->>devcoach: log_lesson(id, topic, level, body, …)
+    Claude-->>-User: Response + 🎓 lesson at the bottom
+
+    User->>+Claude: ✅ know · ❌ don't know · ⏭ skip
+    Claude->>devcoach: submit_feedback → confidence ±1
+    Claude->>Claude: update coaching notebook if warranted
+    Claude-->>-User: acknowledged
+```
+
+See [How it works](how-it-works.md) for the full decision flow.
 
 ---
 
@@ -43,6 +61,14 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 === "Light"
     ![Settings – light theme](screenshots/settings-light.png)
 
+### Lesson detail
+
+=== "Dark"
+    ![Lesson detail – dark theme](screenshots/lesson-redis-cache-stampede-dark.png)
+
+=== "Light"
+    ![Lesson detail – light theme](screenshots/lesson-redis-cache-stampede-light.png)
+
 ---
 
 ## Quick install

devcoach-0.3.9/docs/web-ui.md

@@ -0,0 +1,144 @@
+# Web UI
+
+The devcoach web dashboard provides a visual interface for everything the CLI does.
+
+## Launch
+
+```bash
+devcoach ui              # http://localhost:7860
+devcoach ui --port 8080  # custom port
+```
+
+Or via the MCP tool (Claude can launch it for you):
+
+```
+open_ui({ port: 7860 })
+```
+
+---
+
+## Pages
+
+### Knowledge map (`/`)
+
+Displays your full knowledge map with colour-coded confidence bars:
+
+- **Green** — confidence ≥ 7 (strong)
+- **Yellow** — confidence 4–6 (intermediate)
+- **Red** — confidence ≤ 3 (learning)
+
+**Edit mode** (click `✎ Edit`):
+- `+` / `−` buttons beside each bar to adjust confidence by 1
+- `⇄` button to move a topic to a different group
+- `×` button to delete a topic
+- `+ topic` button in each group header to add a topic directly to that group
+- `+ Add group` / `+ Add topic` buttons in the page header
+- `×` beside group names to delete a group (topics move to Other)
+
+**View mode**: topic names are clickable links that filter the lessons page to that topic.
+
+**Stats bar** (top of page): total lessons, today's count vs. daily limit, this week's count, and current rate-limit status.
+
+=== "Dark"
+    ![Knowledge map – dark theme](screenshots/knowledge-map-dark.png)
+
+=== "Light"
+    ![Knowledge map – light theme](screenshots/knowledge-map-light.png)
+
+---
+
+### Lessons (`/lessons`)
+
+Filterable, sortable table of all delivered lessons.
+
+**Filters:**
+- Period (today / week / month / year / all)
+- Category tag
+- Difficulty level
+- Project / repository / branch / commit hash
+- Starred only
+- Feedback (know / dont_know / none)
+- Free-text search
+- Date range (supports optional time: `2026-04-25T14:30`)
+
+**Sort:** by timestamp, level, topic, title, or feedback. Ascending or descending.
+
+**Pagination:** 25 per page.
+
+**Actions per lesson:**
+- `★` — toggle starred
+- Feedback buttons (✓ / ✗ / clear) — record comprehension, adjusts knowledge confidence
+- Lesson ID link — opens the detail page
+
+=== "Dark"
+    ![Lessons – dark theme](screenshots/lessons-dark.png)
+
+=== "Light"
+    ![Lessons – light theme](screenshots/lessons-light.png)
+
+---
+
+### Lesson detail (`/lessons/<id>`)
+
+Full lesson content laid out in reading order:
+
+- **Title row** — star toggle, title, level badge (junior / mid / senior)
+- **Metadata row** — relative date with tooltip, topic ID, category tags, feedback badge + clear button
+- **TL;DR callout** — one-sentence summary in a highlighted indigo box, always visible above the body
+- **Lesson body** — full markdown content with syntax-highlighted code blocks
+- **Task context** — the coding task that triggered the lesson (when available)
+- **Git metadata** — project, repository (with platform icon + link), branch, commit hash, folder (VSCode deep-link)
+- **Feedback buttons** — ✓ I know this / ✗ I don't know this (hidden once feedback is recorded)
+
+=== "Docker layer caching (Junior)"
+    === "Dark"
+        ![Docker layer caching – dark](screenshots/lesson-docker-layer-cache-dark.png)
+    === "Light"
+        ![Docker layer caching – light](screenshots/lesson-docker-layer-cache-light.png)
+
+=== "PostgreSQL EXPLAIN ANALYZE (Mid)"
+    === "Dark"
+        ![PostgreSQL EXPLAIN ANALYZE – dark](screenshots/lesson-postgresql-explain-analyze-dark.png)
+    === "Light"
+        ![PostgreSQL EXPLAIN ANALYZE – light](screenshots/lesson-postgresql-explain-analyze-light.png)
+
+=== "Git interactive rebase (Mid)"
+    === "Dark"
+        ![Git interactive rebase – dark](screenshots/lesson-git-interactive-rebase-dark.png)
+    === "Light"
+        ![Git interactive rebase – light](screenshots/lesson-git-interactive-rebase-light.png)
+
+=== "CI/CD pipeline stages (Senior)"
+    === "Dark"
+        ![CI/CD pipeline stages – dark](screenshots/lesson-ci-cd-pipeline-stages-dark.png)
+    === "Light"
+        ![CI/CD pipeline stages – light](screenshots/lesson-ci-cd-pipeline-stages-light.png)
+
+=== "Cache stampede (Senior)"
+    === "Dark"
+        ![Cache stampede – dark](screenshots/lesson-redis-cache-stampede-dark.png)
+    === "Light"
+        ![Cache stampede – light](screenshots/lesson-redis-cache-stampede-light.png)
+
+---
+
+### Settings (`/settings`)
+
+- **Max per day** — maximum lessons in a 24-hour window (1–20)
+- **Min gap** — minimum minutes between lessons (0–1440), input as hours + minutes
+- **Export lessons** — download all lessons as JSON
+- **Import lessons** — upload a previously exported JSON file
+- **Export backup** — full zip (settings + knowledge + lessons)
+- **Import backup** — restore from a backup zip
+
+=== "Dark"
+    ![Settings – dark theme](screenshots/settings-dark.png)
+
+=== "Light"
+    ![Settings – light theme](screenshots/settings-light.png)
+
+---
+
+## Keyboard shortcuts
+
+The web UI has no keyboard shortcuts. Use the CLI for faster access to individual commands.

{devcoach-0.3.8 → devcoach-0.3.9}/mkdocs.yml

@@ -27,12 +27,14 @@ theme:
     - navigation.indexes
     - search.highlight
     - content.code.copy
+    - content.tabs.link
     - toc.integrate
   icon:
     repo: fontawesome/brands/github
 
 nav:
   - Home: index.md
+  - How it works: how-it-works.md
   - Getting started: getting-started.md
   - CLI reference: cli.md
   - MCP server: mcp-server.md
@@ -46,7 +48,11 @@ markdown_extensions:
   - admonition
   - pymdownx.highlight:
       anchor_linenums: true
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.tabbed:
       alternate_style: true
   - tables

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

@@ -1,6 +1,6 @@
 [project]
 name = "devcoach"
-version = "0.3.8"
+version = "0.3.9"
 description = "A local MCP server that acts as a progressive technical coach for Claude Code and Claude Desktop"
 readme = "README.md"
 requires-python = ">=3.12"

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

@@ -2,7 +2,7 @@ sonar.projectKey=UltimaPhoenix_dev-coach
 sonar.organization=ultimaphoenix
 
 sonar.projectName=devcoach
-sonar.projectVersion=0.3.8
+sonar.projectVersion=0.3.9
 
 sonar.sources=src
 sonar.tests=tests