cherry-docs 0.2.0__py3-none-any.whl

app/repo_scope.py

@@ -0,0 +1,24 @@
+from typing import Optional
+
+
+def normalize_project_id(project_id: Optional[str], default: str = "default-project") -> str:
+    """
+    Normalize repository/project identifiers to the internal dashed format.
+    Examples:
+    - github.com/owner/repo -> owner-repo
+    - https://github.com/owner/repo.git -> owner-repo
+    - git@github.com:owner/repo.git -> owner-repo
+    """
+    if not project_id:
+        return default
+
+    normalized = project_id.strip()
+    if not normalized:
+        return default
+
+    normalized = normalized.replace("https://", "").replace("http://", "")
+    normalized = normalized.replace("git@github.com:", "").replace("github.com/", "")
+    normalized = normalized.removesuffix(".git")
+    normalized = normalized.strip("/")
+    normalized = normalized.replace("/", "-")
+    return normalized.lower() or default

app/services/agent_protocol.py

@@ -0,0 +1,59 @@
+"""Canonical agent protocol rendering for all supported client rule files."""
+from __future__ import annotations
+
+import tomllib
+from hashlib import sha256
+from pathlib import Path
+
+ROOT_DIR = Path(__file__).resolve().parents[2]
+PROTOCOL_PATH = ROOT_DIR / "docs" / "agent_protocol.toml"
+PROTOCOL_SOURCE = "docs/agent_protocol.toml"
+PROMPT_OUTPUTS = {
+    ".claude/CLAUDE.md": "claude",
+    "AGENTS.md": "agents",
+    "GEMINI.md": "gemini",
+    ".cursorrules": "cursorrules",
+    ".cursor/rules/cherrydocs.mdc": "cursor_mdc",
+}
+
+
+def _load_protocol() -> tuple[dict, str]:
+    raw = PROTOCOL_PATH.read_text(encoding="utf-8")
+    return tomllib.loads(raw), raw
+
+
+def _protocol_metadata(protocol: dict, raw: str) -> dict[str, str]:
+    return {
+        "source": PROTOCOL_SOURCE,
+        "version": str(protocol["meta"]["version"]),
+        "hash": sha256(raw.encode("utf-8")).hexdigest()[:12],
+    }
+
+
+def _generated_comment(version: str, protocol_hash: str) -> str:
+    return f"<!-- Generated from {PROTOCOL_SOURCE} version={version} hash={protocol_hash}; do not edit by hand. -->"
+
+
+def _render_body(protocol: dict, version: str, protocol_hash: str) -> str:
+    meta = protocol["meta"]
+    shared = protocol["shared"]
+    lines = [_generated_comment(version, protocol_hash), meta["title"], ""]
+    lines.extend(f"- {bullet}" for bullet in shared["bullets"])
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_platform_prompt(platform: str) -> str:
+    protocol, raw = _load_protocol()
+    meta = _protocol_metadata(protocol, raw)
+    body = _render_body(protocol, meta["version"], meta["hash"])
+    if platform == "claude":
+        return body
+    if platform in {"agents", "gemini", "cursorrules"}:
+        return f"# Project Rules\n\n{body}"
+    if platform == "cursor_mdc":
+        return "---\ndescription: CherryDocs project protocol\nalwaysApply: true\n---\n\n" + body
+    raise ValueError(f"Unsupported platform: {platform}")
+
+
+def build_prompt_file_map() -> dict[str, str]:
+    return {path: render_platform_prompt(platform) for path, platform in PROMPT_OUTPUTS.items()}

app/services/auto_promote_sessions.py

@@ -0,0 +1,245 @@
+"""Background-friendly auto-promotion for captured AI sessions."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.repo_scope import normalize_project_id
+from app.services.capture_core import LocalCaptureBuffer
+from app.services.internal_memory_agent import MemoryModelProvider
+from app.services.memory_providers import resolve_provider
+from app.services.promoted_memory_pipeline import run_session_promotion
+from app.services.promoted_memory_store import DEFAULT_PROMOTED_ROOT, LocalPromotedMemoryStore
+
+
+class AutoPromotionPolicy(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    min_event_count: int = 3
+    min_candidate_confidence: float = 0.8
+    max_sessions: int = 10
+
+
+class AutoPromotionState(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    session_id: str
+    project_id: str
+    signature: str
+    event_count: int
+    last_event_timestamp: str | None = None
+    last_promoted_at: str = Field(default_factory=lambda: datetime.now(UTC).isoformat())
+
+
+class AutoPromotionSessionResult(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    session_id: str
+    action: str
+    reason: str = ""
+    promoted_count: int = 0
+    highlights: list[str] = Field(default_factory=list)
+    distillation_trace: dict[str, object] | None = None
+
+
+class AutoPromotionRunReport(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    project_id: str
+    processed: list[AutoPromotionSessionResult] = Field(default_factory=list)
+    skipped: list[AutoPromotionSessionResult] = Field(default_factory=list)
+
+
+def _state_dir(buffer_dir: str | Path) -> Path:
+    return Path(buffer_dir).expanduser().resolve() / ".promotion-state"
+
+
+def _state_path(buffer_dir: str | Path, session_id: str) -> Path:
+    safe = session_id.replace("/", "_").replace("\\", "_")
+    return _state_dir(buffer_dir) / f"{safe}.json"
+
+
+def _load_state(buffer_dir: str | Path, session_id: str) -> AutoPromotionState | None:
+    path = _state_path(buffer_dir, session_id)
+    if not path.exists():
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        return AutoPromotionState.model_validate(payload)
+    except Exception:
+        return None
+
+
+def _save_state(buffer_dir: str | Path, state: AutoPromotionState) -> None:
+    path = _state_path(buffer_dir, state.session_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(state.model_dump(mode="json"), indent=2), encoding="utf-8")
+
+
+def list_capture_sessions(buffer_dir: str | Path) -> list[str]:
+    root = Path(buffer_dir).expanduser().resolve()
+    if not root.exists():
+        return []
+    return [
+        path.stem
+        for path in sorted(root.glob("*.jsonl"), key=lambda p: p.stat().st_mtime, reverse=True)
+    ]
+
+
+def _session_signature(events: list[dict]) -> str:
+    relevant = [
+        {
+            "event_type": event.get("event_type"),
+            "timestamp": event.get("timestamp"),
+            "text": str(event.get("text") or "")[:400],
+            "command": event.get("command"),
+            "exit_code": event.get("exit_code"),
+        }
+        for event in events
+    ]
+    payload = json.dumps(relevant, sort_keys=True, ensure_ascii=False)
+    return hashlib.sha1(payload.encode("utf-8"), usedforsecurity=False).hexdigest()
+
+
+def _new_state(project_id: str, session_id: str, events: list[dict]) -> AutoPromotionState:
+    timestamps = [
+        str(event.get("timestamp") or "").strip()
+        for event in events
+        if str(event.get("timestamp") or "").strip()
+    ]
+    return AutoPromotionState(
+        session_id=session_id,
+        project_id=project_id,
+        signature=_session_signature(events),
+        event_count=len(events),
+        last_event_timestamp=timestamps[-1] if timestamps else None,
+    )
+
+
+def _session_matches_scope(events: list[dict], *, project_id: str, branch: str | None) -> bool:
+    if not events:
+        return False
+    normalized_project_id = normalize_project_id(project_id)
+    repos = {
+        normalize_project_id(str(event.get("repo") or ""))
+        for event in events
+        if str(event.get("repo") or "").strip()
+    }
+    if repos:
+        if normalized_project_id not in repos:
+            return False
+    else:
+        # No repo field — fall back to cwd directory name match
+        cwds = {
+            normalize_project_id(Path(str(event.get("cwd") or "")).name)
+            for event in events
+            if str(event.get("cwd") or "").strip()
+        }
+        if cwds and normalized_project_id not in cwds:
+            return False
+    if branch:
+        branches = {
+            str(event.get("branch") or "").strip()
+            for event in events
+            if str(event.get("branch") or "").strip()
+        }
+        if branches and branch not in branches:
+            return False
+    return True
+
+
+def auto_promote_captured_sessions(
+    *,
+    project_id: str,
+    buffer_dir: str | Path = ".cherrydocs/capture",
+    promoted_root: str | Path = DEFAULT_PROMOTED_ROOT,
+    provider: MemoryModelProvider | None = None,
+    project_hint: str | None = None,
+    branch: str | None = None,
+    commit: str | None = None,
+    policy: AutoPromotionPolicy | None = None,
+    memory_profile: str | None = None,
+) -> AutoPromotionRunReport:
+    resolved_policy = policy or AutoPromotionPolicy()
+    resolved_provider = provider or resolve_provider()
+    buffer = LocalCaptureBuffer(buffer_dir)
+    store = LocalPromotedMemoryStore(promoted_root)
+    sessions = list_capture_sessions(buffer_dir)[: resolved_policy.max_sessions]
+
+    existing_records = [
+        r for r in store.load_records(project_id)
+        if not branch or not r.branch or r.branch == branch
+    ]
+    processed: list[AutoPromotionSessionResult] = []
+    skipped: list[AutoPromotionSessionResult] = []
+
+    for session_id in sessions:
+        events = buffer.read(session_id)
+        if not _session_matches_scope(events, project_id=project_id, branch=branch):
+            skipped.append(AutoPromotionSessionResult(
+                session_id=session_id, action="skip",
+                reason="session outside requested project/branch scope",
+            ))
+            continue
+        if len(events) < resolved_policy.min_event_count:
+            skipped.append(AutoPromotionSessionResult(
+                session_id=session_id, action="skip",
+                reason=f"too few events ({len(events)} < {resolved_policy.min_event_count})",
+            ))
+            continue
+
+        state = _load_state(buffer_dir, session_id)
+        current_state = _new_state(project_id, session_id, events)
+        if state and state.project_id == project_id and state.signature == current_state.signature:
+            skipped.append(AutoPromotionSessionResult(
+                session_id=session_id, action="skip",
+                reason="no new captured evidence since last promotion",
+            ))
+            continue
+
+        report = run_session_promotion(
+            events=events,
+            session_id=session_id,
+            project_id=project_id,
+            provider=resolved_provider,
+            project_hint=project_hint,
+            branch=branch,
+            commit=commit,
+            existing_records=existing_records,
+            min_confidence=resolved_policy.min_candidate_confidence,
+            memory_profile=memory_profile,
+        )
+        session_records = [r for r in report.session_records if r.memory_type != "noise"]
+        if not session_records:
+            skipped.append(AutoPromotionSessionResult(
+                session_id=session_id, action="skip",
+                reason="no high-confidence durable memory candidates",
+            ))
+            _save_state(buffer_dir, current_state)
+            continue
+
+        existing_records = store.upsert_records(project_id, report.promotion.records)
+        _save_state(buffer_dir, current_state)
+        processed.append(AutoPromotionSessionResult(
+            session_id=session_id,
+            action="promote",
+            promoted_count=len(session_records),
+            highlights=[r.summary for r in session_records[:3]],
+            distillation_trace=report.distillation_trace.model_dump(mode="json"),
+        ))
+
+    return AutoPromotionRunReport(project_id=project_id, processed=processed, skipped=skipped)
+
+
+__all__ = [
+    "AutoPromotionPolicy",
+    "AutoPromotionRunReport",
+    "AutoPromotionSessionResult",
+    "auto_promote_captured_sessions",
+    "list_capture_sessions",
+]

app/services/capture_adapters.py

@@ -0,0 +1,89 @@
+"""Shared append helpers for capture integrations."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from app.services.capture_core import (
+    CaptureEvent,
+    CaptureEventType,
+    LocalCaptureBuffer,
+    build_capture_event,
+)
+
+_TEST_COMMAND_MARKERS = (
+    "pytest",
+    "pnpm test",
+    "npm test",
+    "yarn test",
+    "bun test",
+    "vitest",
+    "jest",
+    "go test",
+    "cargo test",
+    "mix test",
+    "rspec",
+    "phpunit",
+)
+
+
+def infer_capture_event_type(*, tool_name: str | None = None, command: str | None = None) -> CaptureEventType:
+    normalized_command = " ".join(str(command or "").split()).lower()
+    if normalized_command and any(marker in normalized_command for marker in _TEST_COMMAND_MARKERS):
+        return CaptureEventType.TEST_RESULT
+    if str(tool_name or "").strip() == "Bash":
+        return CaptureEventType.SHELL_RESULT
+    return CaptureEventType.TOOL_RESULT
+
+
+def enrich_capture_metadata(
+    *,
+    event_type: CaptureEventType,
+    command: str | None = None,
+    exit_code: int | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    enriched = dict(metadata or {})
+    if event_type == CaptureEventType.TEST_RESULT:
+        enriched.setdefault("capture_kind", "verification")
+        enriched.setdefault("verification_kind", "test")
+        if exit_code is not None:
+            enriched.setdefault("verification_status", "passed" if exit_code == 0 else "failed")
+    elif event_type == CaptureEventType.SHELL_RESULT and command:
+        enriched.setdefault("capture_kind", "command")
+    return enriched
+
+
+def append_capture_event(
+    *,
+    buffer_dir: str | Path,
+    source: str,
+    event_type: CaptureEventType,
+    session_id: str,
+    cwd: str,
+    text: str | None = None,
+    files: list[str] | None = None,
+    command: str | None = None,
+    exit_code: int | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> CaptureEvent:
+    merged_metadata = enrich_capture_metadata(
+        event_type=event_type,
+        command=command,
+        exit_code=exit_code,
+        metadata=metadata,
+    )
+    event = build_capture_event(
+        source=source,
+        event_type=event_type,
+        session_id=session_id,
+        cwd=cwd,
+        text=text,
+        files=files,
+        command=command,
+        exit_code=exit_code,
+        metadata=merged_metadata,
+    )
+    LocalCaptureBuffer(buffer_dir).append(event)
+    return event

app/services/capture_core.py

@@ -0,0 +1,164 @@
+"""Shared capture-core primitives for CLI and hook-based adapters."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Dict, List
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.repo_scope import normalize_project_id
+
+
+class CaptureEventType(StrEnum):
+    SESSION_START = "session_start"
+    SESSION_END = "session_end"
+    USER_PROMPT = "user_prompt"
+    ASSISTANT_OUTPUT = "assistant_output"
+    TOOL_RESULT = "tool_result"
+    SHELL_RESULT = "shell_result"
+    TEST_RESULT = "test_result"
+    REMEMBER = "remember"
+
+
+class CaptureEvent(BaseModel):
+    """Normalized event emitted by any capture adapter."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    source: str
+    session_id: str = "unknown-session"
+    event_type: CaptureEventType
+    timestamp: str
+    cwd: str
+    repo: str | None = None
+    branch: str | None = None
+    text: str | None = None
+    files: List[str] = Field(default_factory=list)
+    command: str | None = None
+    exit_code: int | None = None
+    commit: str | None = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+def now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _run_git(args: List[str], cwd: str) -> str | None:
+    try:
+        proc = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=2,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return proc.stdout.strip() or None
+
+
+def capture_repo_context(cwd: str | None = None) -> Dict[str, Any]:
+    """Best-effort git context for a local capture event."""
+
+    resolved_cwd = str(Path(cwd or ".").resolve())
+    repo_root = _run_git(["rev-parse", "--show-toplevel"], resolved_cwd)
+    if not repo_root:
+        return {
+            "cwd": resolved_cwd,
+            "repo": None,
+            "branch": None,
+            "commit": None,
+            "files": [],
+        }
+
+    branch = _run_git(["rev-parse", "--abbrev-ref", "HEAD"], repo_root)
+    commit = _run_git(["rev-parse", "HEAD"], repo_root)
+    remote = _run_git(["remote", "get-url", "origin"], repo_root) or _run_git(
+        ["config", "--get", "remote.origin.url"],
+        repo_root,
+    )
+    changed = _run_git(["status", "--short"], repo_root) or ""
+    files: List[str] = []
+    for line in changed.splitlines():
+        candidate = line[3:].strip() if len(line) >= 4 else line.strip()
+        if candidate:
+            files.append(candidate)
+
+    return {
+        "cwd": resolved_cwd,
+        "repo": normalize_project_id(remote or Path(repo_root).name),
+        "branch": branch,
+        "commit": commit,
+        "files": files,
+    }
+
+
+def build_capture_event(
+    *,
+    source: str,
+    event_type: CaptureEventType,
+    session_id: str | None = None,
+    cwd: str | None = None,
+    text: str | None = None,
+    files: List[str] | None = None,
+    command: str | None = None,
+    exit_code: int | None = None,
+    metadata: Dict[str, Any] | None = None,
+) -> CaptureEvent:
+    """Create a normalized capture event with best-effort repo context."""
+
+    repo_context = capture_repo_context(cwd)
+    merged_files = list(files or repo_context.get("files") or [])
+    return CaptureEvent(
+        source=source,
+        session_id=(session_id or "unknown-session"),
+        event_type=event_type,
+        timestamp=now_iso(),
+        cwd=repo_context["cwd"],
+        repo=repo_context.get("repo"),
+        branch=repo_context.get("branch"),
+        text=text,
+        files=merged_files,
+        command=command,
+        exit_code=exit_code,
+        commit=repo_context.get("commit"),
+        metadata=dict(metadata or {}),
+    )
+
+
+class LocalCaptureBuffer:
+    """Simple JSONL-backed local event buffer for the capture POC."""
+
+    def __init__(self, root: str | Path):
+        self.root = Path(root)
+
+    def path_for(self, session_id: str) -> Path:
+        safe = (session_id or "unknown-session").replace("/", "_").replace("\\", "_")
+        return self.root / f"{safe}.jsonl"
+
+    def append(self, event: CaptureEvent) -> Path:
+        path = self.path_for(event.session_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(event.model_dump(mode="json"), ensure_ascii=False))
+            handle.write("\n")
+        return path
+
+    def read(self, session_id: str) -> List[Dict[str, Any]]:
+        path = self.path_for(session_id)
+        if not path.exists():
+            return []
+        rows: List[Dict[str, Any]] = []
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            rows.append(json.loads(line))
+        return rows