devcoach 0.1.0__py3-none-any.whl

devcoach/core/detect.py

@@ -0,0 +1,132 @@
+"""File-based tech stack detection for devcoach onboarding."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+# (glob_pattern, topic_id, default_confidence)
+# Confidence 6 = Intermediate (working knowledge); 7 = confident use.
+STACK_SIGNALS: list[tuple[str, str, int]] = [
+    ("package.json", "javascript", 6),
+    ("tsconfig*.json", "typescript", 6),
+    ("requirements*.txt", "python", 6),
+    ("pyproject.toml", "python", 6),
+    ("setup.py", "python", 6),
+    ("go.mod", "go", 6),
+    ("Cargo.toml", "rust", 6),
+    ("pom.xml", "java", 6),
+    ("build.gradle", "java", 6),
+    ("build.gradle.kts", "java", 6),
+    ("*.csproj", "csharp", 6),
+    ("Gemfile", "ruby", 6),
+    ("composer.json", "php", 6),
+    ("Dockerfile", "docker", 7),
+    ("Dockerfile.*", "docker", 7),
+    ("docker-compose.yml", "docker_compose", 7),
+    ("docker-compose.yaml", "docker_compose", 7),
+    ("docker-compose.*.yml", "docker_compose", 7),
+    (".github/workflows/*.yml", "github_actions", 6),
+    (".github/workflows/*.yaml", "github_actions", 6),
+    (".gitlab-ci.yml", "gitlab_ci", 6),
+    ("Jenkinsfile", "ci_cd", 6),
+    ("*.tf", "terraform", 6),
+    ("*.sql", "sql", 5),
+    (".git", "git", 7),
+    ("kubernetes/*.yaml", "kubernetes", 6),
+    ("kubernetes/*.yml", "kubernetes", 6),
+    ("k8s/*.yaml", "kubernetes", 6),
+    ("*.bicep", "azure", 6),
+    ("serverless.yml", "aws", 6),
+    ("serverless.yaml", "aws", 6),
+    ("template.yaml", "aws", 5),  # SAM
+    ("angular.json", "angular", 6),
+    ("svelte.config.*", "svelte", 6),
+    ("nuxt.config.*", "vue", 6),
+    ("vite.config.*", "javascript", 6),
+]
+
+# package.json devDependencies/dependencies → framework topic
+_JS_FRAMEWORK_MAP: dict[str, str] = {
+    "react": "react",
+    "react-dom": "react",
+    "vue": "vue",
+    "@angular/core": "angular",
+    "svelte": "svelte",
+    "next": "nextjs",
+    "nuxt": "vue",
+    "fastify": "fastify",
+    "express": "express",
+    "koa": "express",
+    "@nestjs/core": "node_js",
+}
+
+# requirements.txt / pyproject.toml → framework topic
+_PYTHON_FRAMEWORK_MAP: dict[str, str] = {
+    "django": "django",
+    "flask": "flask",
+    "fastapi": "fastapi",
+    "starlette": "fastapi",
+    "tornado": "python",
+    "aiohttp": "python",
+    "sqlalchemy": "postgresql",
+    "celery": "python",
+}
+
+
+def detect_stack(folder: str) -> dict[str, int]:
+    """Scan *folder* for technology signals.
+
+    Returns {topic_id: confidence} as suggestions for the onboarding
+    conversation. Values are defaults only — the user should confirm or
+    adjust each one.
+    """
+    root = Path(folder)
+    result: dict[str, int] = {}
+
+    def _add(topic: str, confidence: int) -> None:
+        # Keep the highest confidence seen for a topic
+        if result.get(topic, -1) < confidence:
+            result[topic] = confidence
+
+    for pattern, topic, confidence in STACK_SIGNALS:
+        if list(root.glob(pattern)):
+            _add(topic, confidence)
+
+    # Deeper inspection: package.json → JS frameworks
+    pkg_path = root / "package.json"
+    if pkg_path.exists():
+        try:
+            pkg = json.loads(pkg_path.read_text(encoding="utf-8", errors="replace"))
+            all_deps: set[str] = set()
+            all_deps.update(pkg.get("dependencies", {}).keys())
+            all_deps.update(pkg.get("devDependencies", {}).keys())
+            for dep, framework_topic in _JS_FRAMEWORK_MAP.items():
+                if dep in all_deps:
+                    _add(framework_topic, 6)
+        except Exception:
+            pass
+
+    # Deeper inspection: pyproject.toml / requirements → Python frameworks
+    for req_file in ("requirements.txt", "requirements-dev.txt", "requirements/base.txt"):
+        req_path = root / req_file
+        if req_path.exists():
+            try:
+                text = req_path.read_text(encoding="utf-8", errors="replace").lower()
+                for pkg_name, framework_topic in _PYTHON_FRAMEWORK_MAP.items():
+                    if pkg_name in text:
+                        _add(framework_topic, 6)
+            except Exception:
+                pass
+
+    pyproject_path = root / "pyproject.toml"
+    if pyproject_path.exists():
+        try:
+            text = pyproject_path.read_text(encoding="utf-8", errors="replace").lower()
+            for pkg_name, framework_topic in _PYTHON_FRAMEWORK_MAP.items():
+                if pkg_name in text:
+                    _add(framework_topic, 6)
+        except Exception:
+            pass
+
+    return result

devcoach/core/git.py

@@ -0,0 +1,97 @@
+"""Git context auto-detection for devcoach."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+
+def _run(*args: str) -> str | None:
+    """Run a git command and return stdout, or None on any error."""
+    try:
+        result = subprocess.run(
+            list(args),
+            capture_output=True,
+            text=True,
+            timeout=3,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip() or None
+    except Exception:
+        pass
+    return None
+
+
+def _parse_remote(remote: str | None) -> tuple[str | None, str | None]:
+    """Parse a git remote URL into (repository, platform).
+
+    Handles:
+      git@github.com:org/repo.git  →  ("org/repo", "github")
+      https://github.com/org/repo  →  ("org/repo", "github")
+      https://gitlab.com/org/repo.git  →  ("org/repo", "gitlab")
+      https://bitbucket.org/org/repo  →  ("org/repo", "bitbucket")
+      anything else with a remote  →  (remote, "local")
+      no remote  →  (None, None)
+    """
+    if not remote:
+        return None, None
+
+    _PLATFORM_MAP = {
+        "github.com": "github",
+        "gitlab.com": "gitlab",
+        "bitbucket.org": "bitbucket",
+    }
+
+    # SSH: git@host:org/repo.git
+    ssh_match = re.match(r"git@([^:]+):(.+?)(?:\.git)?$", remote)
+    if ssh_match:
+        host = ssh_match.group(1).lower()
+        path = ssh_match.group(2)
+        platform = _PLATFORM_MAP.get(host, "local")
+        return path, platform
+
+    # HTTPS: https://host/org/repo[.git]
+    https_match = re.match(r"https?://([^/]+)/(.+?)(?:\.git)?$", remote)
+    if https_match:
+        host = https_match.group(1).lower()
+        path = https_match.group(2)
+        platform = _PLATFORM_MAP.get(host, "local")
+        return path, platform
+
+    return remote, "local"
+
+
+def detect_git_context() -> dict[str, str | None]:
+    """Detect git metadata from the current working directory.
+
+    Returns a dict with keys: project, repository, branch, commit_hash,
+    folder, repository_platform. Any field that cannot be determined is None.
+    All subprocess calls have a 3-second timeout and never raise.
+    """
+    folder = str(Path.cwd())
+    branch = _run("git", "rev-parse", "--abbrev-ref", "HEAD")
+    commit = _run("git", "rev-parse", "HEAD")
+    remote = _run("git", "remote", "get-url", "origin")
+
+    repository, platform = _parse_remote(remote)
+
+    if repository:
+        # Use last path component as project name
+        project: str | None = repository.rstrip("/").split("/")[-1]
+    else:
+        # Fall back to cwd folder name
+        project = Path(folder).name or None
+
+    # HEAD detached check
+    if branch == "HEAD":
+        branch = None
+
+    return {
+        "project": project,
+        "repository": repository,
+        "branch": branch,
+        "commit_hash": commit,
+        "folder": folder,
+        "repository_platform": platform,
+    }

devcoach/core/models.py

@@ -0,0 +1,104 @@
+"""Pydantic v2 models for devcoach."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Literal
+
+from pydantic import BaseModel, field_serializer, field_validator
+
+# ── Domain type aliases ────────────────────────────────────────────────────
+
+Level = Literal["junior", "mid", "senior"]
+RepositoryPlatform = Literal["github", "gitlab", "bitbucket", "local"]
+Feedback = Literal["know", "dont_know"]
+
+
+# ── Models ─────────────────────────────────────────────────────────────────
+
+
+class Lesson(BaseModel):
+    """A coaching lesson delivered to the user."""
+
+    id: str
+    timestamp: datetime
+    topic_id: str
+    categories: list[str]
+    title: str
+    level: Level
+    summary: str
+    task_context: str | None = None
+    project: str | None = None
+    repository: str | None = None
+    branch: str | None = None
+    commit_hash: str | None = None
+    folder: str | None = None
+    repository_platform: RepositoryPlatform | None = None
+    starred: bool = False
+    feedback: Feedback | None = None
+
+    @field_validator("timestamp", mode="before")
+    @classmethod
+    def parse_and_normalize_timestamp(cls, v: str | datetime) -> datetime:
+        """Accept any ISO 8601 string or datetime; always return UTC-aware datetime."""
+        if isinstance(v, datetime):
+            return v if v.tzinfo else v.replace(tzinfo=UTC)
+        try:
+            dt = datetime.fromisoformat(v)
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=UTC)
+            return dt.astimezone(UTC)
+        except ValueError:
+            raise ValueError(f"Cannot parse timestamp {v!r} — expected ISO 8601")
+
+    @field_serializer("timestamp")
+    def serialize_timestamp(self, v: datetime) -> str:
+        """Serialize to UTC ISO 8601 string with Z suffix for JSON output."""
+        return v.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    @property
+    def timestamp_iso(self) -> str:
+        """UTC ISO 8601 string with Z suffix, e.g. '2025-01-15T20:30:00Z'."""
+        return self.timestamp.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class KnowledgeEntry(BaseModel):
+    """A single topic in the knowledge map."""
+
+    topic: str
+    confidence: int  # 0-10
+
+
+class KnowledgeGroup(BaseModel):
+    """A named group containing a list of topic IDs."""
+
+    name: str
+    topics: list[str]
+
+
+class Profile(BaseModel):
+    """The user's full knowledge map with group definitions."""
+
+    knowledge: list[KnowledgeEntry]
+    groups: list[KnowledgeGroup]
+
+
+class Settings(BaseModel):
+    """Server configuration settings."""
+
+    max_per_day: int = 2
+    min_gap_minutes: int = 240  # replaces min_hours_between (4h default)
+
+
+class KnowledgeUpdate(BaseModel):
+    """Input for update_knowledge tool."""
+
+    topic: str
+    delta: int
+
+
+class RateLimitResult(BaseModel):
+    """Result from the check_rate_limit tool."""
+
+    allowed: bool
+    reason: str | None = None

devcoach/core/prompts.py

@@ -0,0 +1,52 @@
+"""Lesson template builders by knowledge level for devcoach."""
+
+from __future__ import annotations
+
+from devcoach.core.models import Lesson
+
+
+def format_lesson_for_display(lesson: Lesson) -> str:
+    """Format a Lesson as the markdown block appended to a coaching response."""
+    level_label = lesson.level.capitalize()
+    category_str = " · ".join(lesson.categories)
+    lines = [
+        "---",
+        f"🎓 **devcoach** · {category_str} · Level: {level_label}",
+        "",
+        f"**{lesson.title}**",
+        "",
+        lesson.summary,
+    ]
+    if lesson.task_context:
+        lines += ["", f"*Context: {lesson.task_context}*"]
+    return "\n".join(lines)
+
+
+def build_prompt_for_level(topic: str, context: str, confidence: int) -> str:
+    """Select the appropriate prompt template based on confidence score.
+
+    0-3  → junior
+    4-6  → mid
+    7-9  → senior
+    10   → topic mastered, returns empty string
+    """
+    if confidence <= 3:
+        return (
+            f"Explain '{topic}' for a beginner. Use a simple analogy. "
+            f"Avoid jargon. Show a minimal code example if helpful. "
+            f"Connect the explanation to: {context}"
+        )
+    elif confidence <= 6:
+        return (
+            f"Explain the 'why' behind '{topic}' for an intermediate developer. "
+            f"Mention two or three alternative approaches and their tradeoffs. "
+            f"Connect the explanation to: {context}"
+        )
+    elif confidence <= 9:
+        return (
+            f"Give a senior-level perspective on '{topic}'. "
+            f"Focus on edge cases, production tradeoffs, and historical context. "
+            f"Assume the reader already knows the basics. "
+            f"Connect the explanation to: {context}"
+        )
+    return ""