devmemory-cli 0.1.0.dev0__py3-none-any.whl

devmemory/environment.py

@@ -0,0 +1,67 @@
+"""Best-effort snapshot of the local toolchain.
+
+Attached to development versions (Phase 3+) so history records what produced it.
+Collects nothing personal - versions and platform strings only.
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+
+from devmemory.domain.models import EnvironmentInfo
+
+
+def _first_line(executable: str, *args: str) -> str | None:
+    path = shutil.which(executable)
+    if path is None:
+        return None
+    try:
+        proc = subprocess.run(  # noqa: S603 - fixed executable, arg list, no shell
+            [path, *args],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    text = (proc.stdout or proc.stderr).strip()
+    return text.splitlines()[0].strip() if text else None
+
+
+def _detect_package_manager(repo_path: Path) -> str | None:
+    markers = {
+        "uv.lock": "uv",
+        "poetry.lock": "poetry",
+        "Pipfile.lock": "pipenv",
+        "pdm.lock": "pdm",
+        "requirements.txt": "pip",
+        "pyproject.toml": "pip",
+        "package-lock.json": "npm",
+        "pnpm-lock.yaml": "pnpm",
+        "yarn.lock": "yarn",
+        "go.mod": "go",
+        "Cargo.toml": "cargo",
+    }
+    for marker, name in markers.items():
+        if (repo_path / marker).exists():
+            return name
+    return None
+
+
+def collect_environment(repo_path: Path | str = ".") -> EnvironmentInfo:
+    repo_path = Path(repo_path)
+    return EnvironmentInfo(
+        python_version=platform.python_version(),
+        platform=f"{platform.system()} {platform.release()}",
+        machine=platform.machine(),
+        git_version=_first_line("git", "--version"),
+        entire_version=_first_line("entire", "version"),
+        package_manager=_detect_package_manager(repo_path),
+    )
+
+
+__all__ = ["collect_environment"]

devmemory/logging.py

@@ -0,0 +1,148 @@
+"""Structured logging with secret redaction.
+
+DevMemory must be diagnosable (which operation failed, which integration, was
+project state changed, what next) without ever writing a credential to a log.
+``configure_logging`` wires up structlog; a redaction processor scrubs both
+known-sensitive keys and any value that matches a live environment secret.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Any
+
+import structlog
+
+_REDACTED = "***redacted***"
+
+_SENSITIVE_KEY_MARKERS = (
+    "token",
+    "secret",
+    "password",
+    "passwd",
+    "api_key",
+    "apikey",
+    "authorization",
+    "auth_header",
+    "access_key",
+    "private_key",
+    "client_secret",
+)
+
+_SENSITIVE_ENV_MARKERS = (
+    "TOKEN",
+    "SECRET",
+    "PASSWORD",
+    "API_KEY",
+    "APIKEY",
+    "ACCESS_KEY",
+    "PRIVATE_KEY",
+)
+
+_configured = False
+
+
+def _live_secret_values() -> set[str]:
+    """Non-trivial values of environment variables that look like secrets."""
+    values: set[str] = set()
+    for name, value in os.environ.items():
+        if not value or len(value) < 6:
+            continue
+        if any(marker in name.upper() for marker in _SENSITIVE_ENV_MARKERS):
+            values.add(value)
+    return values
+
+
+def _redact_value(value: Any, secrets: set[str]) -> Any:
+    if isinstance(value, str):
+        if value in secrets:
+            return _REDACTED
+        redacted = value
+        for secret in secrets:
+            if secret and secret in redacted:
+                redacted = redacted.replace(secret, _REDACTED)
+        return redacted
+    if isinstance(value, dict):
+        return {k: _redact_mapping_entry(k, v, secrets) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return type(value)(_redact_value(v, secrets) for v in value)
+    return value
+
+
+def _redact_mapping_entry(key: Any, value: Any, secrets: set[str]) -> Any:
+    if isinstance(key, str) and any(marker in key.lower() for marker in _SENSITIVE_KEY_MARKERS):
+        return _REDACTED
+    return _redact_value(value, secrets)
+
+
+def _redaction_processor(
+    _logger: object, _method: str, event_dict: structlog.types.EventDict
+) -> structlog.types.EventDict:
+    secrets = _live_secret_values()
+    return {k: _redact_mapping_entry(k, v, secrets) for k, v in event_dict.items()}
+
+
+def configure_logging(*, level: str = "INFO", json_logs: bool | None = None) -> None:
+    """Initialise structlog. Safe to call more than once (later calls reconfigure).
+
+    ``json_logs`` defaults to ``True`` when stderr is not a TTY (CI, pipes),
+    ``False`` (rich console renderer) when it is.
+    """
+    global _configured
+
+    if json_logs is None:
+        json_logs = not sys.stderr.isatty()
+
+    numeric_level = getattr(logging, level.upper(), logging.INFO)
+
+    shared_processors: list[structlog.types.Processor] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso", utc=True),
+        structlog.processors.StackInfoRenderer(),
+        _redaction_processor,
+    ]
+
+    renderer: structlog.types.Processor = (
+        structlog.processors.JSONRenderer()
+        if json_logs
+        else structlog.dev.ConsoleRenderer(colors=sys.stderr.isatty())
+    )
+
+    structlog.configure(
+        processors=[*shared_processors, renderer],
+        wrapper_class=structlog.make_filtering_bound_logger(numeric_level),
+        # Resolve sys.stderr lazily per log line - pytest's captured streams are
+        # swapped and closed between tests, so a cached stream reference breaks.
+        logger_factory=_lazy_stderr_factory,
+        cache_logger_on_first_use=False,
+    )
+    _configured = True
+
+
+def _lazy_stderr_factory(*_args: object) -> structlog.PrintLogger:
+    return structlog.PrintLogger(file=sys.stderr)
+
+
+def get_logger(name: str | None = None) -> structlog.stdlib.BoundLogger:
+    """Return a bound logger, configuring logging with defaults on first use."""
+    if not _configured:
+        configure_logging()
+    return structlog.get_logger(name)  # type: ignore[no-any-return]
+
+
+def redact_secrets(text: str) -> str:
+    """Replace any live environment-secret value found in ``text``.
+
+    Used before text produced by an external LLM is stored or displayed.
+    """
+    out = text
+    for secret in _live_secret_values():
+        if secret in out:
+            out = out.replace(secret, _REDACTED)
+    return out
+
+
+__all__ = ["configure_logging", "get_logger", "redact_secrets"]

devmemory/mcp/__init__.py

@@ -0,0 +1,12 @@
+"""DevMemory's Model Context Protocol server.
+
+``build_server`` returns a configured :class:`fastmcp.FastMCP` exposing the same
+development memory the dashboard shows - so an AI coding agent can ask "what
+happened here before?" before it makes a change. Requires the ``mcp`` extra.
+"""
+
+from __future__ import annotations
+
+from devmemory.mcp.server import build_server
+
+__all__ = ["build_server"]

devmemory/mcp/server.py

@@ -0,0 +1,225 @@
+"""The DevMemory MCP server.
+
+Read-only. Every tool returns collected facts (Git, Entire, tests, metrics) or a
+rule-based risk read over them - never an LLM interpretation. The server holds
+one thread-safe :class:`ProjectContext` for its lifetime.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from devmemory.adapters.graph import GraphImpact
+from devmemory.domain.enums import RequirementStatus
+from devmemory.domain.taskloop import Issue, NormalizedState
+from devmemory.services.agent_context import (
+    ChangeGuidance,
+    ProjectBrief,
+    VersionBrief,
+    VersionReport,
+    change_guidance,
+    project_brief,
+    recent_history,
+    version_brief,
+    version_report,
+)
+from devmemory.services.analytics import AnalyticsSummary, analytics_summary
+from devmemory.services.context import ProjectContext
+from devmemory.services.memory import MemoryQuery, PreviousAttempt, previous_attempts
+from devmemory.services.taskloop import engine as taskloop
+from devmemory.services.trace import DevelopmentTrace, development_trace
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+_INSTRUCTIONS = """\
+DevMemory records every AI-assisted change as a Development Version: the Git diff,
+the Entire checkpoint (intent + agent + model), the test and metric results, and
+whether it regressed anything.
+
+State-aware coding loop: call get_state(task_id) before starting or resuming
+work, do the implementation with your own tools, commit, then refresh_state to
+re-collect evidence and get the new status (IN_PROGRESS / NEEDS_WORK / READY /
+BLOCKED). Continue while NEEDS_WORK; stop at READY; escalate at BLOCKED.
+
+Call check_before_change BEFORE editing files - it reports whether this area has
+failed here before. Use get_project_context for orientation, get_version_history
+and get_previous_attempts to look back, and get_development_trace to see how one
+version's intent led to its result.
+"""
+
+
+def build_server(repo_path: Path | str | None = None) -> FastMCP:
+    from fastmcp import FastMCP
+
+    resolved = Path(repo_path) if repo_path is not None else None
+    holder: dict[str, ProjectContext] = {}
+
+    def ctx() -> ProjectContext:
+        if "ctx" not in holder:
+            holder["ctx"] = ProjectContext.load(resolved, thread_safe=True)
+        return holder["ctx"]
+
+    @asynccontextmanager
+    async def lifespan(_server: FastMCP) -> AsyncIterator[None]:
+        try:
+            yield
+        finally:
+            existing = holder.pop("ctx", None)
+            if existing is not None:
+                existing.close()
+
+    mcp: FastMCP = FastMCP("devmemory", instructions=_INSTRUCTIONS, lifespan=lifespan)
+
+    @mcp.tool
+    def get_project_context() -> ProjectBrief:
+        """Orientation for this repo: branch/HEAD, whether HEAD is checkpointed,
+        version count and success rate, open features, the latest version, recent
+        adverse versions, and things to be careful about."""
+        return project_brief(ctx())
+
+    @mcp.tool
+    def get_version_history(limit: int = 20, feature: str | None = None) -> list[VersionBrief]:
+        """Recent development versions, newest first. Optionally filter by feature."""
+        return recent_history(ctx(), limit=limit, feature=feature)
+
+    @mcp.tool
+    def get_version(ref: str) -> VersionReport:
+        """One version in full: the flattened brief, its intent->result trace, and
+        its parent commit. ``ref`` accepts ``v7``, ``7``, or a commit prefix."""
+        return version_report(ctx(), ref)
+
+    @mcp.tool
+    def get_development_trace(ref: str) -> DevelopmentTrace:
+        """The ordered chain for one version: intent -> agent -> checkpoint ->
+        commit -> files -> tests -> metrics -> status -> analysis."""
+        return development_trace(ctx(), ref)
+
+    @mcp.tool
+    def get_previous_attempts(
+        files: list[str] | None = None,
+        intent: str | None = None,
+        feature: str | None = None,
+        include_successes: bool = False,
+        limit: int = 10,
+    ) -> list[PreviousAttempt]:
+        """Past versions that touched the same files / feature / intent, ranked by
+        relevance. Adverse attempts only unless ``include_successes`` is set. Each
+        result explains why it matched and what to do about it."""
+        return previous_attempts(
+            ctx(),
+            MemoryQuery(
+                files=files or [],
+                intent=intent,
+                feature=feature,
+                include_successes=include_successes,
+                limit=limit,
+            ),
+        )
+
+    @mcp.tool
+    def check_before_change(
+        files: list[str] | None = None,
+        intent: str = "",
+        feature: str | None = None,
+    ) -> ChangeGuidance:
+        """Pre-flight check: given the files you are about to edit (and optionally
+        your intent / the feature), returns a verdict - proceed | caution |
+        high-risk - with the specific prior failures to read first. Call this
+        before editing."""
+        return change_guidance(ctx(), files=files or [], intent=intent or None, feature=feature)
+
+    @mcp.tool
+    def search_versions(query: str, limit: int = 10) -> list[VersionBrief]:
+        """Full-text search over version intents, features, and changed files."""
+        from devmemory.services.versions import search_versions as _search
+
+        return [version_brief(v) for v in _search(ctx(), query, limit=limit)]
+
+    @mcp.tool
+    def get_change_impact(ref: str) -> GraphImpact | None:
+        """The entity-level blast radius for a version (Entire `graph` plugin):
+        added / removed / renamed / signature-changed / body-changed symbols with
+        dependent counts. ``None`` if the plugin is not installed."""
+        from devmemory.services.impact import version_impact
+
+        return version_impact(ctx(), ref)
+
+    @mcp.tool
+    def get_analytics() -> AnalyticsSummary:
+        """Development intelligence across all versions: regression leaderboard,
+        feature attempts, file churn, agent effectiveness, trend, and
+        repeatedly-failed approaches."""
+        return analytics_summary(ctx())
+
+    # -- the state-aware coding loop -------------------------------------
+
+    @mcp.tool
+    def create_task(goal: str, test_command: str | None = None) -> NormalizedState:
+        """Start a task: normalize ``goal`` into explicit requirements, pin the
+        base commit, and return the first state. Call this once per human task,
+        then drive the loop with get_state / refresh_state."""
+        task = taskloop.create_task(ctx(), goal=goal, test_command=test_command)
+        return taskloop.get_state(ctx(), task.id)
+
+    @mcp.tool
+    def get_state(task_id: str) -> NormalizedState:
+        """The current normalized project state for a task: requirements, git,
+        checkpoint, tests, impact, unresolved items, recommended focus, and the
+        overall status. Read this before starting or resuming work. It orients
+        you - still inspect the real repository with your own tools."""
+        return taskloop.get_state(ctx(), task_id)
+
+    @mcp.tool
+    def refresh_state(task_id: str) -> NormalizedState:
+        """Re-collect all evidence (git, Entire, tests, optional graph),
+        re-evaluate requirements, recompute the overall status, store a snapshot,
+        and return the complete new state. Call this after you commit meaningful
+        progress."""
+        return taskloop.refresh_state(ctx(), task_id)
+
+    @mcp.tool
+    def get_checkpoint(checkpoint_id: str) -> dict[str, object]:
+        """Compact metadata for one Entire checkpoint: intent, agent, model,
+        associated commit, sessions, token total. Not a full transcript."""
+        return taskloop.get_checkpoint(ctx(), checkpoint_id)
+
+    @mcp.tool
+    def report_issue(task_id: str, description: str, blocking: bool = False) -> Issue:
+        """Record an unresolved item for a task. Set ``blocking=True`` when you
+        cannot safely continue without a human decision - that forces the task to
+        BLOCKED on the next refresh."""
+        return taskloop.report_issue(
+            ctx(), task_id=task_id, description=description, blocking=blocking
+        )
+
+    @mcp.tool
+    def set_requirement_status(
+        task_id: str, requirement_id: str, status: str, note: str = ""
+    ) -> NormalizedState:
+        """Record your own verdict for one requirement (status: COMPLETE |
+        PARTIAL | INCOMPLETE | UNKNOWN) after you have implemented and verified
+        it. The engine still independently checks tests + tree state before it
+        will report READY. Returns the refreshed state."""
+        return taskloop.set_requirement_status(
+            ctx(),
+            task_id=task_id,
+            requirement_id=requirement_id,
+            status=RequirementStatus(status.upper()),
+            note=note,
+        )
+
+    @mcp.tool
+    def mark_complete(task_id: str) -> NormalizedState:
+        """Request a completion evaluation. This runs a full refresh and returns
+        the state - it never blindly marks READY. You are done only if the
+        returned overall_status is READY."""
+        return taskloop.mark_complete(ctx(), task_id)
+
+    return mcp
+
+
+__all__ = ["build_server"]

devmemory/paths.py

@@ -0,0 +1,112 @@
+"""Filesystem layout for a DevMemory-tracked project.
+
+Everything DevMemory writes into a target repository lives under a single hidden
+directory, ``.devmemory/``. This module is the one place that knows its shape.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+DEVMEMORY_DIRNAME = ".devmemory"
+CONFIG_FILENAME = "config.json"
+CONFIG_LOCAL_FILENAME = "config.local.json"
+DB_FILENAME = "metadata.db"
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectPaths:
+    """Resolved absolute paths for one project's DevMemory data."""
+
+    repo_root: Path
+    """The project/repository root - the parent of ``.devmemory/``."""
+
+    root: Path
+    """The ``.devmemory/`` directory itself."""
+
+    config: Path
+    """Committed, non-secret configuration (``.devmemory/config.json``)."""
+
+    config_local: Path
+    """Git-ignored local overrides (``.devmemory/config.local.json``)."""
+
+    db: Path
+    """SQLite metadata database."""
+
+    versions_dir: Path
+    """Human-readable per-version JSON mirrors."""
+
+    artifacts_dir: Path
+    """Compressed project snapshots."""
+
+    outbox_dir: Path
+    """Pending Databricks events awaiting sync."""
+
+    runs_dir: Path
+    """Structured logs, one file per ``devmemory checkpoint`` run."""
+
+    cache_dir: Path
+    """Derived data that can be safely deleted (diffs, graph results)."""
+
+    @classmethod
+    def for_root(cls, repo_root: Path) -> ProjectPaths:
+        repo_root = repo_root.resolve()
+        root = repo_root / DEVMEMORY_DIRNAME
+        return cls(
+            repo_root=repo_root,
+            root=root,
+            config=root / CONFIG_FILENAME,
+            config_local=root / CONFIG_LOCAL_FILENAME,
+            db=root / DB_FILENAME,
+            versions_dir=root / "versions",
+            artifacts_dir=root / "artifacts",
+            outbox_dir=root / "outbox",
+            runs_dir=root / "runs",
+            cache_dir=root / "cache",
+        )
+
+    def ensure_scaffold(self) -> None:
+        """Create every directory in the layout. Idempotent."""
+        for directory in (
+            self.root,
+            self.versions_dir,
+            self.artifacts_dir,
+            self.outbox_dir,
+            self.runs_dir,
+            self.cache_dir,
+        ):
+            directory.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def exists(self) -> bool:
+        return self.root.is_dir()
+
+
+def find_project_root(start: Path | None = None) -> Path | None:
+    """Walk upward from ``start`` (default: cwd) looking for a ``.devmemory/`` dir.
+
+    Returns the containing directory, or ``None`` if the filesystem root is
+    reached without finding one.
+    """
+    current = (start or Path.cwd()).resolve()
+    for candidate in (current, *current.parents):
+        if (candidate / DEVMEMORY_DIRNAME).is_dir():
+            return candidate
+    return None
+
+
+def find_project_paths(start: Path | None = None) -> ProjectPaths | None:
+    root = find_project_root(start)
+    return ProjectPaths.for_root(root) if root is not None else None
+
+
+__all__ = [
+    "CONFIG_FILENAME",
+    "CONFIG_LOCAL_FILENAME",
+    "DB_FILENAME",
+    "DEVMEMORY_DIRNAME",
+    "ProjectPaths",
+    "find_project_paths",
+    "find_project_root",
+]

devmemory/pipeline/__init__.py

@@ -0,0 +1,7 @@
+"""The ``devmemory checkpoint`` pipeline: turn a git commit + its context into a
+persisted :class:`~devmemory.domain.models.DevelopmentVersion`.
+"""
+
+from devmemory.pipeline.checkpoint import CheckpointResult, run_checkpoint
+
+__all__ = ["CheckpointResult", "run_checkpoint"]