devcoach 0.3.8__tar.gz → 0.3.10__tar.gz

devcoach-0.3.10/.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.10}/.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.10}/.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.10}/.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.10}/.gitignore

@@ -197,6 +197,8 @@ cython_debug/
 # Claude Code
 .claude/
 .playwright-mcp/
+.playwright-cli/
+config.example.json
 
 # Cursor
 #  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devcoach
-Version: 0.3.8
+Version: 0.3.10
 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
@@ -245,12 +245,35 @@ Description-Content-Type: text/markdown
 
 ## 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
+flowchart TD
+    A([Task completed]) --> B[Check rate limit]
+    B -->|denied| Z([Silent])
+    B -->|allowed| D
+
+    subgraph loop["coaching loop"]
+        D[Select topic & depth]
+        E[Compose & deliver]
+        G[log_lesson]
+    end
+
+    D -->|nothing| Z
+    D -->|found| E
+    E --> G
+    G --> F([Done])
+    G -.->|prompts| U(["You: ✅ ❌ ⏭"])
+
+    style loop fill:none,stroke:#AAAAAA,stroke-dasharray:5 5,color:#757575
+    classDef action fill:#D4E4D8,stroke:#8BAF96,color:#1E1E1E
+    classDef term   fill:#E8E8E4,stroke:#AAAAAA,color:#1E1E1E
+    classDef user   fill:#F5EDE3,stroke:#D4A27F,color:#1E1E1E
+
+    class B,D,E,G action
+    class A,F,Z term
+    class U user
+```
+
+→ [Full decision flow: session startup · lesson selection · depth calibration](https://ultimaphoenix.github.io/dev-coach/how-it-works/)
 
 Everything runs **locally**. No data leaves your machine. One SQLite file at `~/.devcoach/coaching.db`.
 

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

@@ -14,12 +14,35 @@
 
 ## 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
+flowchart TD
+    A([Task completed]) --> B[Check rate limit]
+    B -->|denied| Z([Silent])
+    B -->|allowed| D
+
+    subgraph loop["coaching loop"]
+        D[Select topic & depth]
+        E[Compose & deliver]
+        G[log_lesson]
+    end
+
+    D -->|nothing| Z
+    D -->|found| E
+    E --> G
+    G --> F([Done])
+    G -.->|prompts| U(["You: ✅ ❌ ⏭"])
+
+    style loop fill:none,stroke:#AAAAAA,stroke-dasharray:5 5,color:#757575
+    classDef action fill:#D4E4D8,stroke:#8BAF96,color:#1E1E1E
+    classDef term   fill:#E8E8E4,stroke:#AAAAAA,color:#1E1E1E
+    classDef user   fill:#F5EDE3,stroke:#D4A27F,color:#1E1E1E
+
+    class B,D,E,G action
+    class A,F,Z term
+    class U user
+```
+
+→ [Full decision flow: session startup · lesson selection · depth calibration](https://ultimaphoenix.github.io/dev-coach/how-it-works/)
 
 Everything runs **locally**. No data leaves your machine. One SQLite file at `~/.devcoach/coaching.db`.
 

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

@@ -0,0 +1,102 @@
+# 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 LR
+    A([Start]) --> B{First run?}
+    B -- yes --> C[Detect stack]
+    C --> D[Confirm topics\n& groups]
+    D --> E[Save profile]
+    B -- no --> F[Load profile\n& notebook]
+    E & F --> G([Ready])
+
+    subgraph onboarding["onboarding"]
+        C
+        D
+        E
+    end
+
+    style onboarding fill:none,stroke:#AAAAAA,stroke-dasharray:5 5,color:#757575
+    classDef action fill:#D4E4D8,stroke:#8BAF96,color:#1E1E1E
+    classDef term   fill:#E8E8E4,stroke:#AAAAAA,color:#1E1E1E
+
+    class C,D,E,F action
+    class A,G term
+```
+
+---
+
+## 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([Task completed]) --> B[Check rate limit]
+    B -->|denied| Z([Silent])
+    B -->|allowed| D
+
+    subgraph loop["coaching loop"]
+        D[Select topic & depth]
+        E[Compose & deliver]
+        G[log_lesson]
+    end
+
+    D -->|nothing| Z
+    D -->|found| E
+    E --> G
+    G --> F([Done])
+    G -.->|prompts| U(["You: ✅ ❌ ⏭"])
+
+    style loop fill:none,stroke:#AAAAAA,stroke-dasharray:5 5,color:#757575
+    classDef action fill:#D4E4D8,stroke:#8BAF96,color:#1E1E1E
+    classDef term   fill:#E8E8E4,stroke:#AAAAAA,color:#1E1E1E
+    classDef user   fill:#F5EDE3,stroke:#D4A27F,color:#1E1E1E
+
+    class B,D,E,G action
+    class A,F,Z term
+    class U user
+```
+
+---
+
+## Lesson selection
+
+When a teachable concept is found, devcoach walks this priority list from top to bottom
+and picks the first match. Depth is then calibrated to the per-topic confidence score.
+
+| Priority | Trigger | Condition |
+|:---:|---|---|
+| ① | Notebook follow-up | The coaching notebook flagged an angle relevant to the current task |
+| ② | Profile pitfall | A pitfall committed or avoided on a profile topic |
+| ③ | Profile pattern | An interesting pattern on a profile topic worth formalising |
+| ④ | Off-profile pitfall | A pitfall on a topic prominent in the task but absent from the profile |
+| ⑤ | Knowledge gap | A profile topic with confidence < 5 |
+| ⑥ | Deep-dive | A profile topic at confidence 4–6, not yet mastered |
+
+First match wins. No match → silent.
+
+---
+
+## 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.10}/docs/index.md

@@ -8,12 +8,35 @@ 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
+flowchart TD
+    A([Task completed]) --> B[Check rate limit]
+    B -->|denied| Z([Silent])
+    B -->|allowed| D
+
+    subgraph loop["coaching loop"]
+        D[Select topic & depth]
+        E[Compose & deliver]
+        G[log_lesson]
+    end
+
+    D -->|nothing| Z
+    D -->|found| E
+    E --> G
+    G --> F([Done])
+    G -.->|prompts| U(["You: ✅ ❌ ⏭"])
+
+    style loop fill:none,stroke:#AAAAAA,stroke-dasharray:5 5,color:#757575
+    classDef action fill:#D4E4D8,stroke:#8BAF96,color:#1E1E1E
+    classDef term   fill:#E8E8E4,stroke:#AAAAAA,color:#1E1E1E
+    classDef user   fill:#F5EDE3,stroke:#D4A27F,color:#1E1E1E
+
+    class B,D,E,G action
+    class A,F,Z term
+    class U user
+```
+
+→ [Full decision flow: session startup · lesson selection · depth calibration](how-it-works.md)
 
 ---
 
@@ -43,6 +66,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