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

devmemory/services/impact.py

@@ -0,0 +1,47 @@
+"""Change-impact for a version: stored result, or computed on demand.
+
+Thin service over :class:`GraphAdapter` + :class:`GraphImpactRepository`. When a
+version has no stored impact and the plugin is available, it is computed once and
+cached.
+"""
+
+from __future__ import annotations
+
+from devmemory.adapters.graph import GraphImpact, GraphStatus
+from devmemory.services.context import ProjectContext
+from devmemory.services.versions import get_version
+from devmemory.storage.graph_impacts import GraphImpactRepository
+
+
+def graph_status(ctx: ProjectContext) -> GraphStatus:
+    status = ctx.graph.probe()
+    return status.model_copy(update={"detail": status.detail or _enabled_note(ctx)})
+
+
+def version_impact(
+    ctx: ProjectContext, ref: str, *, compute_if_missing: bool = True
+) -> GraphImpact | None:
+    version = get_version(ctx, ref)
+    repo = GraphImpactRepository(ctx.db)
+
+    stored = repo.get(version.version_id)
+    if stored is not None:
+        return stored
+    if not compute_if_missing or not ctx.graph.is_available:
+        return None
+
+    impact = ctx.graph.commit_impact(version.git_commit)
+    if impact is None:
+        return None
+    computed = impact.model_copy(update={"version_id": version.version_id})
+    repo.set(version.version_id, computed)
+    return computed
+
+
+def _enabled_note(ctx: ProjectContext) -> str | None:
+    if not ctx.config.graph.enabled:
+        return "graph.enabled is false; impact is computed on request only"
+    return None
+
+
+__all__ = ["graph_status", "version_impact"]

devmemory/services/memory.py

@@ -0,0 +1,212 @@
+"""Development memory: surface previous attempts so failed approaches aren't repeated.
+
+Given a scope (files being touched, a feature, an intent), find the historical
+versions that are relevant - especially the ones that failed or regressed - and
+return them with a short "why this matched" and a recommendation.
+
+Retrieval is deliberately simple (file overlap + feature + FTS keyword match +
+status). Embeddings can be layered on later without changing this interface.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from devmemory.domain.enums import VersionStatus
+from devmemory.domain.models import DevelopmentVersion
+from devmemory.services.context import ProjectContext
+from devmemory.storage.repositories import FeatureRepository
+from devmemory.storage.versions import VersionRepository
+
+_ADVERSE = {VersionStatus.REGRESSION, VersionStatus.ERROR}
+
+
+class PreviousAttempt(BaseModel):
+    version_id: str
+    version_number: int
+    status: str
+    intent: str | None
+    agent: str | None
+    feature: str | None
+    git_commit: str
+    files: list[str]
+    change_summary: str
+    result: str
+    recommendation: str | None
+    is_adverse: bool
+    score: float
+    matched_on: list[str]
+
+
+class MemoryQuery(BaseModel):
+    files: list[str] = []
+    feature: str | None = None
+    intent: str | None = None
+    include_successes: bool = False
+    limit: int = 10
+
+
+def previous_attempts(ctx: ProjectContext, query: MemoryQuery) -> list[PreviousAttempt]:
+    repo = VersionRepository(ctx.db)
+    project_id = ctx.config.project_id
+    want_files = {_norm(f) for f in query.files}
+
+    feature_id: str | None = None
+    if query.feature:
+        feat = FeatureRepository(ctx.db).get_by_name(project_id, query.feature)
+        feature_id = feat.feature_id if feat else None
+
+    candidates: dict[str, DevelopmentVersion] = {}
+    if query.intent:
+        for v in _by_ids(repo, repo.search_ids(project_id, query.intent, limit=40)):
+            candidates[v.version_id] = v
+    for v in repo.page(project_id, limit=500, ascending=False):
+        candidates.setdefault(v.version_id, v)
+
+    scored: list[PreviousAttempt] = []
+    for v in candidates.values():
+        attempt = _score(v, want_files, feature_id, query)
+        if attempt is not None:
+            scored.append(attempt)
+
+    scored.sort(key=lambda a: (a.score, a.version_number), reverse=True)
+    return scored[: query.limit]
+
+
+def _score(
+    v: DevelopmentVersion,
+    want_files: set[str],
+    feature_id: str | None,
+    query: MemoryQuery,
+) -> PreviousAttempt | None:
+    is_adverse = v.status in _ADVERSE or bool(v.regressions)
+    if not is_adverse and not query.include_successes:
+        return None
+
+    matched: list[str] = []
+    score = 0.0
+
+    v_files = {_norm(f.path) for f in v.changed_files}
+    overlap = want_files & v_files
+    if overlap:
+        score += 3.0 + 0.5 * len(overlap)
+        matched.append("files: " + ", ".join(sorted(overlap)[:3]))
+
+    if feature_id and v.feature_id == feature_id:
+        score += 2.5
+        matched.append(f"feature: {query.feature}")
+
+    if query.intent and v.intent:
+        shared = _keyword_overlap(query.intent, v.intent)
+        if shared:
+            score += 1.0 + 0.4 * len(shared)
+            matched.append("intent: " + ", ".join(sorted(shared)[:3]))
+
+    if is_adverse:
+        score += 1.5
+
+    if score <= 0 or not matched:
+        return None
+
+    return PreviousAttempt(
+        version_id=v.version_id,
+        version_number=v.version_number,
+        status=v.status.value,
+        intent=v.intent,
+        agent=v.agent,
+        feature=v.feature_id.split(":", 1)[-1] if v.feature_id else None,
+        git_commit=v.git_commit,
+        files=[f.path for f in v.changed_files],
+        change_summary=_change_summary(v),
+        result=_result_summary(v),
+        recommendation=_recommendation(v),
+        is_adverse=is_adverse,
+        score=round(score, 2),
+        matched_on=matched,
+    )
+
+
+def _change_summary(v: DevelopmentVersion) -> str:
+    files = ", ".join(f.path for f in v.changed_files[:3])
+    more = f" (+{len(v.changed_files) - 3} more)" if len(v.changed_files) > 3 else ""
+    return f"{files}{more}  +{v.lines_added}/-{v.lines_removed}" if files else v.intent or "—"
+
+
+def _result_summary(v: DevelopmentVersion) -> str:
+    parts: list[str] = []
+    for r in v.regressions:
+        if r.before is not None and r.after is not None:
+            parts.append(f"{r.metric or r.kind} {r.before:g} → {r.after:g}")
+        elif r.detail:
+            parts.append(r.detail)
+    if not parts and v.tests and v.tests.ran and not v.tests.all_passed:
+        parts.append(f"{v.tests.failed} tests failed")
+    if not parts:
+        for m in v.metrics:
+            if m.before is not None and m.after is not None:
+                parts.append(f"{m.name} {m.before:g} → {m.after:g}")
+    return "; ".join(parts) or v.status.value
+
+
+def _recommendation(v: DevelopmentVersion) -> str | None:
+    if v.analysis and v.analysis.recommendation:
+        return v.analysis.recommendation
+    if v.status is VersionStatus.REGRESSION or v.regressions:
+        return "This approach regressed here - avoid repeating it, or address the cause first."
+    if v.status is VersionStatus.ERROR:
+        return "This approach errored - check the fix that followed before retrying."
+    return None
+
+
+def _keyword_overlap(a: str, b: str) -> set[str]:
+    return _keywords(a) & _keywords(b)
+
+
+_STOP = {
+    "the",
+    "a",
+    "an",
+    "to",
+    "of",
+    "and",
+    "or",
+    "for",
+    "in",
+    "on",
+    "with",
+    "is",
+    "add",
+    "fix",
+    "update",
+    "change",
+    "make",
+    "use",
+    "improve",
+    "implement",
+    "this",
+    "that",
+    "it",
+    "be",
+    "into",
+    "from",
+    "so",
+}
+
+
+def _keywords(text: str) -> set[str]:
+    return {
+        w
+        for w in "".join(c if c.isalnum() else " " for c in text.lower()).split()
+        if len(w) > 2 and w not in _STOP
+    }
+
+
+def _by_ids(repo: VersionRepository, ids: list[str]) -> list[DevelopmentVersion]:
+    return [v for vid in ids if (v := repo.get(vid)) is not None]
+
+
+def _norm(path: str) -> str:
+    return path.replace("\\", "/").lstrip("./").lower()
+
+
+__all__ = ["MemoryQuery", "PreviousAttempt", "previous_attempts"]

devmemory/services/projects.py

@@ -0,0 +1,226 @@
+"""Project lifecycle: ``init`` and ``status``."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from devmemory.adapters.git import GitAdapter
+from devmemory.config import DevMemoryConfig
+from devmemory.domain.enums import FeatureStatus, VersionStatus
+from devmemory.domain.errors import (
+    GitRepositoryNotFoundError,
+    ProjectAlreadyInitializedError,
+)
+from devmemory.domain.models import EntireStatus, EnvironmentInfo, Project
+from devmemory.environment import collect_environment
+from devmemory.logging import get_logger
+from devmemory.paths import DEVMEMORY_DIRNAME, ProjectPaths
+from devmemory.services.context import ProjectContext
+from devmemory.storage.repositories import FeatureRepository, ProjectRepository
+from devmemory.storage.versions import VersionRepository
+
+_log = get_logger(__name__)
+
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+
+def slugify(text: str) -> str:
+    slug = _SLUG_RE.sub("-", text.strip().lower()).strip("-")
+    return slug or "project"
+
+
+class InitReport(BaseModel):
+    project: Project
+    config_path: str
+    db_path: str
+    git_detected: bool
+    git_version: str | None
+    entire: EntireStatus
+    environment: EnvironmentInfo
+    gitignore_updated: bool
+
+
+class ProjectStatusReport(BaseModel):
+    project: Project
+    branch: str | None
+    head_sha: str | None
+    head_subject: str | None
+    working_tree_clean: bool
+    entire: EntireStatus
+    version_count: int = 0
+    latest_version_id: str | None = None
+    latest_status: str | None = None
+    latest_intent: str | None = None
+    head_has_version: bool = False
+    last_regression_id: str | None = None
+    open_features: list[str] = []
+    latest_metrics: dict[str, float | None] = {}
+
+
+def init_project(
+    repo_path: Path | str,
+    *,
+    name: str | None = None,
+    project_id: str | None = None,
+    force: bool = False,
+    entire_probe: EntireStatus | None = None,
+) -> InitReport:
+    """Create ``.devmemory/`` for a repository and register the project."""
+    repo_path = Path(repo_path).resolve()
+
+    git = GitAdapter(repo_path)
+    if not git.is_repository():
+        raise GitRepositoryNotFoundError(
+            f"{repo_path} is not inside a git repository.",
+        )
+    repo_root = git.repo_root()
+    paths = ProjectPaths.for_root(repo_root)
+
+    if paths.exists and not force:
+        raise ProjectAlreadyInitializedError(
+            f"DevMemory is already initialized at {paths.root}.",
+            hint="Pass --force to re-create the configuration (history is preserved).",
+        )
+
+    paths.ensure_scaffold()
+
+    resolved_name = name or repo_root.name
+    resolved_id = slugify(project_id or resolved_name)
+
+    config = _load_or_default_config(paths, project_id=resolved_id, project_name=resolved_name)
+    config.save(paths)
+
+    ctx = ProjectContext.for_paths(paths, config)
+    try:
+        repo = ProjectRepository(ctx.db)
+        project = repo.get_by_id(resolved_id)
+        if project is None:
+            project = repo.create(
+                project_id=resolved_id,
+                name=resolved_name,
+                repo_path=str(repo_root),
+            )
+    finally:
+        ctx.close()
+
+    gitignore_updated = _ensure_repo_gitignore(repo_root)
+    entire = entire_probe or EntireStatus()
+
+    _log.info(
+        "project.init",
+        project_id=resolved_id,
+        repo=str(repo_root),
+        force=force,
+    )
+
+    return InitReport(
+        project=project,
+        config_path=str(paths.config),
+        db_path=str(paths.db),
+        git_detected=True,
+        git_version=git.git_version(),
+        entire=entire,
+        environment=collect_environment(repo_root),
+        gitignore_updated=gitignore_updated,
+    )
+
+
+def project_status(
+    ctx: ProjectContext, *, entire_probe: EntireStatus | None = None
+) -> ProjectStatusReport:
+    repo = ProjectRepository(ctx.db)
+    project = repo.get()
+    if project is None:  # pragma: no cover - context load implies a project row
+        raise ProjectAlreadyInitializedError("No project row found; re-run `devmemory init`.")
+
+    versions = VersionRepository(ctx.db)
+    features = FeatureRepository(ctx.db)
+
+    head = ctx.git.head_sha()
+    subject = ctx.git.commit(head).subject if head else None
+
+    latest = versions.latest(project.project_id)
+    head_version = versions.find_by_commit(project.project_id, head) if head else None
+    last_regression = next(
+        (
+            v.version_id
+            for v in versions.page(project.project_id, limit=200, ascending=False)
+            if v.status is VersionStatus.REGRESSION
+        ),
+        None,
+    )
+    open_features = [
+        f.name
+        for f in features.list_all(project.project_id)
+        if f.status not in (FeatureStatus.COMPLETE, FeatureStatus.NOT_STARTED)
+    ]
+
+    return ProjectStatusReport(
+        project=project,
+        branch=ctx.git.current_branch(),
+        head_sha=head,
+        head_subject=subject,
+        working_tree_clean=not ctx.git.is_dirty(),
+        entire=entire_probe or EntireStatus(),
+        version_count=versions.count(project.project_id),
+        latest_version_id=latest.version_id if latest else None,
+        latest_status=latest.status.value if latest else None,
+        latest_intent=latest.intent if latest else None,
+        head_has_version=head_version is not None,
+        last_regression_id=last_regression,
+        open_features=open_features,
+        latest_metrics={m.name: m.after for m in latest.metrics} if latest else {},
+    )
+
+
+# --- helpers ---------------------------------------------------------------------
+
+
+def _load_or_default_config(
+    paths: ProjectPaths, *, project_id: str, project_name: str
+) -> DevMemoryConfig:
+    if paths.config.is_file():
+        try:
+            existing = DevMemoryConfig.load(paths)
+        except Exception:
+            _log.warning("project.init.config_unreadable", path=str(paths.config))
+        else:
+            return existing
+    return DevMemoryConfig.default_for(project_id=project_id, project_name=project_name)
+
+
+_GITIGNORE_BLOCK = f"""
+# DevMemory - local-only data (config.json is committed, the rest is not)
+{DEVMEMORY_DIRNAME}/config.local.json
+{DEVMEMORY_DIRNAME}/metadata.db
+{DEVMEMORY_DIRNAME}/metadata.db-*
+{DEVMEMORY_DIRNAME}/artifacts/
+{DEVMEMORY_DIRNAME}/outbox/
+{DEVMEMORY_DIRNAME}/runs/
+{DEVMEMORY_DIRNAME}/cache/
+"""
+
+
+def _ensure_repo_gitignore(repo_root: Path) -> bool:
+    gitignore = repo_root / ".gitignore"
+    marker = f"{DEVMEMORY_DIRNAME}/metadata.db"
+    existing = gitignore.read_text(encoding="utf-8") if gitignore.is_file() else ""
+    if marker in existing:
+        return False
+    with gitignore.open("a", encoding="utf-8") as handle:
+        if existing and not existing.endswith("\n"):
+            handle.write("\n")
+        handle.write(_GITIGNORE_BLOCK)
+    return True
+
+
+__all__ = [
+    "InitReport",
+    "ProjectStatusReport",
+    "init_project",
+    "project_status",
+    "slugify",
+]

devmemory/services/restore.py

@@ -0,0 +1,194 @@
+"""Restoring the working tree to an earlier development version - safely.
+
+Restore is potentially destructive, so:
+
+1. Resolve the target version to its git commit.
+2. Inspect the working tree; refuse if there are uncommitted changes unless the
+   caller explicitly allows it.
+3. Record a safety reference: a tag at the current HEAD, plus a ``git stash
+   create`` object if the tree is dirty.
+4. Only then move HEAD - detached checkout by default, ``git reset --hard`` only
+   when explicitly asked.
+5. Record a ``restore`` event.
+
+``preview`` performs steps 1-2 and reports what *would* happen, touching nothing.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import UTC, datetime
+
+from pydantic import BaseModel
+
+from devmemory.domain.errors import DevMemoryError, RestoreSafetyError
+from devmemory.logging import get_logger
+from devmemory.services.context import ProjectContext
+from devmemory.services.versions import get_version
+
+_log = get_logger(__name__)
+
+
+class RestorePreview(BaseModel):
+    version_id: str
+    target_commit: str
+    target_subject: str
+    current_commit: str | None
+    current_branch: str | None
+    already_there: bool
+    working_tree_clean: bool
+    uncommitted: list[str]
+    untracked: list[str]
+    safety_tag: str
+    warning: str
+
+
+class RestoreResult(BaseModel):
+    version_id: str
+    mode: str  # 'detach' | 'hard'
+    target_commit: str
+    previous_commit: str | None
+    safety_tag: str
+    stash_ref: str | None
+    message: str
+
+
+def restore_preview(ctx: ProjectContext, ref: str) -> RestorePreview:
+    v = get_version(ctx, ref)
+    state = ctx.git.working_tree_state()
+    current = ctx.git.head_sha()
+    target_info = ctx.git.commit(v.git_commit)
+
+    return RestorePreview(
+        version_id=v.version_id,
+        target_commit=v.git_commit,
+        target_subject=target_info.subject,
+        current_commit=current,
+        current_branch=state.branch,
+        already_there=current == v.git_commit,
+        working_tree_clean=state.is_clean,
+        uncommitted=[*state.staged, *state.unstaged],
+        untracked=state.untracked,
+        safety_tag=_safety_tag_name(),
+        warning=(
+            f"This moves the working tree to the state of {v.version_id.upper()} "
+            f"(git {v.git_commit[:12]}). "
+            + (
+                "Your uncommitted changes would be at risk."
+                if state.has_uncommitted_changes
+                else "A safety tag is created at the current HEAD first."
+            )
+        ),
+    )
+
+
+def restore_version(
+    ctx: ProjectContext,
+    ref: str,
+    *,
+    mode: str = "detach",
+    allow_dirty: bool = False,
+) -> RestoreResult:
+    if mode not in ("detach", "hard"):
+        raise DevMemoryError(f"unknown restore mode {mode!r}")
+
+    v = get_version(ctx, ref)
+    state = ctx.git.working_tree_state()
+    current = ctx.git.head_sha()
+
+    if current == v.git_commit and state.is_clean:
+        return RestoreResult(
+            version_id=v.version_id,
+            mode=mode,
+            target_commit=v.git_commit,
+            previous_commit=current,
+            safety_tag="",
+            stash_ref=None,
+            message=f"Already at {v.version_id.upper()} with a clean tree; nothing to do.",
+        )
+
+    if state.has_uncommitted_changes and not allow_dirty:
+        raise RestoreSafetyError(
+            f"{len(state.staged) + len(state.unstaged)} uncommitted change(s) would be at risk.",
+            hint="Commit or stash them, or pass --allow-dirty to keep a safety stash and proceed.",
+        )
+
+    safety_tag = _safety_tag_name()
+    ctx.git.create_tag(
+        safety_tag,
+        "HEAD",
+        message=f"devmemory: state before restoring {v.version_id}",
+    )
+    stash_ref = ctx.git.stash_create() if state.has_uncommitted_changes else None
+
+    try:
+        if mode == "hard":
+            ctx.git.reset_hard(v.git_commit)
+        else:
+            ctx.git.checkout_detached(v.git_commit)
+    except DevMemoryError:
+        _log.error("restore.failed", version=v.version_id, safety_tag=safety_tag)
+        raise
+
+    _record_restore(ctx, v.version_id, v.git_commit, current, safety_tag, stash_ref, mode)
+    _log.info(
+        "restore.done",
+        version=v.version_id,
+        commit=v.git_commit[:12],
+        mode=mode,
+        safety_tag=safety_tag,
+    )
+    recover = f"git reset --hard {safety_tag}" if mode == "hard" else "git switch -"
+    return RestoreResult(
+        version_id=v.version_id,
+        mode=mode,
+        target_commit=v.git_commit,
+        previous_commit=current,
+        safety_tag=safety_tag,
+        stash_ref=stash_ref,
+        message=(
+            f"Working tree restored to {v.version_id.upper()} ({v.git_commit[:12]}). "
+            f"Recover the previous state with `{recover}`"
+            + (f" and `git stash apply {stash_ref}`" if stash_ref else "")
+            + "."
+        ),
+    )
+
+
+def _safety_tag_name() -> str:
+    return "devmemory/safety/" + datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+
+
+def _record_restore(
+    ctx: ProjectContext,
+    version_id: str,
+    target: str,
+    previous: str | None,
+    safety_tag: str,
+    stash_ref: str | None,
+    mode: str,
+) -> None:
+    with ctx.db.transaction() as conn:
+        conn.execute(
+            "INSERT INTO events (event_id, project_id, version_id, type, source, payload_json, "
+            "created_at) VALUES (?, ?, ?, 'restore', 'devmemory', ?, ?)",
+            (
+                uuid.uuid4().hex,
+                ctx.config.project_id,
+                version_id,
+                json.dumps(
+                    {
+                        "target": target,
+                        "previous": previous,
+                        "safety_tag": safety_tag,
+                        "stash_ref": stash_ref,
+                        "mode": mode,
+                    }
+                ),
+                datetime.now(UTC).isoformat(),
+            ),
+        )
+
+
+__all__ = ["RestorePreview", "RestoreResult", "restore_preview", "restore_version"]