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

devmemory/cli/checkpoint.py

@@ -0,0 +1,199 @@
+"""``devmemory checkpoint`` - record the current commit as a development version."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from devmemory.cli._render import console, hint, status_text, success, warn
+from devmemory.domain.enums import MetricDirection, VersionStatus
+from devmemory.domain.errors import DevMemoryError
+from devmemory.domain.models import Metric
+from devmemory.pipeline.checkpoint import CheckpointRequest, run_checkpoint
+from devmemory.services.context import ProjectContext
+
+_LOWER_IS_BETTER_HINTS = (
+    "latency",
+    "duration",
+    "time",
+    "loss",
+    "error",
+    "cost",
+    "memory",
+    "p50",
+    "p95",
+    "p99",
+    "rt",
+)
+
+
+def checkpoint_command(
+    intent: Annotated[
+        str | None,
+        typer.Option("--intent", help="What was requested (defaults to the checkpoint)."),
+    ] = None,
+    feature: Annotated[
+        str | None, typer.Option("--feature", "-f", help="Feature area this change belongs to.")
+    ] = None,
+    agent: Annotated[
+        str | None, typer.Option("--agent", help="AI agent, if not read from the checkpoint.")
+    ] = None,
+    status: Annotated[
+        str | None,
+        typer.Option("--status", help="Override the derived status (SUCCESS, REGRESSION, ...)."),
+    ] = None,
+    tests_passed: Annotated[
+        int | None, typer.Option("--tests-passed", help="Passing test count (skips the runner).")
+    ] = None,
+    tests_failed: Annotated[
+        int | None, typer.Option("--tests-failed", help="Failing test count (skips the runner).")
+    ] = None,
+    run_tests: Annotated[
+        bool,
+        typer.Option("--run-tests/--no-run-tests", help="Run the configured test command."),
+    ] = True,
+    metrics: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--metric", "-m", help="Metric as name=after or name=before:after (repeatable)."
+        ),
+    ] = None,
+    metrics_file: Annotated[
+        str | None,
+        typer.Option("--metrics-file", help="Path to a JSON metrics file to read."),
+    ] = None,
+    errors: Annotated[
+        list[str] | None, typer.Option("--error", "-e", help="An error encountered (repeatable).")
+    ] = None,
+    snapshot: Annotated[
+        bool,
+        typer.Option("--snapshot/--no-snapshot", help="Archive the source tree for this version."),
+    ] = True,
+    allow_no_entire: Annotated[
+        bool,
+        typer.Option("--allow-no-entire", help="Record even without an Entire checkpoint."),
+    ] = False,
+    force: Annotated[
+        bool, typer.Option("--force", help="Re-record the version for this commit in place.")
+    ] = False,
+    as_json: Annotated[bool, typer.Option("--json", help="Emit the result as JSON.")] = False,
+) -> None:
+    """Turn the current git commit + its Entire/test/metric context into a Development Version."""
+    request = CheckpointRequest(
+        intent=intent,
+        feature=feature,
+        agent=agent,
+        status=_parse_status(status),
+        tests_passed=tests_passed,
+        tests_failed=tests_failed,
+        run_tests=run_tests,
+        metrics=[_parse_metric(m) for m in (metrics or [])],
+        metrics_file=metrics_file,
+        errors=list(errors or []),
+        snapshot=snapshot,
+        allow_no_entire=allow_no_entire,
+        force=force,
+    )
+
+    with ProjectContext.load() as ctx:
+        result = run_checkpoint(ctx, request)
+
+    if as_json:
+        console.print_json(
+            json.dumps(
+                {
+                    "created": result.created,
+                    "version": result.version.model_dump(mode="json"),
+                    "run_id": result.run_log.run_id,
+                    "warnings": result.warnings,
+                }
+            )
+        )
+        return
+
+    v = result.version
+    if not result.created:
+        warn(f"{v.version_id} already records commit {v.git_commit[:12]} - nothing to do.")
+        hint("Pass --force to re-record it.")
+        return
+
+    console.print()
+    console.print(
+        f"[bold]{v.version_id}[/bold]  ", status_text(v.status), f"  [dim]{v.git_commit[:12]}[/dim]"
+    )
+    if v.intent:
+        console.print(f"  intent   {v.intent}")
+    if v.primary_checkpoint:
+        cp = v.primary_checkpoint
+        marker = (
+            ""
+            if not cp.is_uncertain
+            else f" [yellow](confidence {cp.association_confidence:.2f})[/yellow]"
+        )
+        console.print(
+            f"  entire   {cp.checkpoint_id}  [dim]{cp.association_method.value}[/dim]{marker}"
+        )
+    if v.agent:
+        console.print(f"  agent    {v.agent}" + (f"  [dim]{v.model}[/dim]" if v.model else ""))
+    if v.feature_id:
+        console.print(f"  feature  {v.feature_id.split(':', 1)[-1]}")
+    console.print(
+        f"  changes  {v.files_changed} files  "
+        f"[green]+{v.lines_added}[/green] [red]-{v.lines_removed}[/red]"
+    )
+    if v.tests and v.tests.ran:
+        console.print(f"  tests    {v.tests.passed} passed / {v.tests.failed} failed")
+    for m in v.metrics:
+        arrow = "→"
+        console.print(
+            f"  {m.name:<8} {m.before} {arrow} {m.after}" + (f" {m.unit}" if m.unit else "")
+        )
+
+    for w in result.warnings:
+        warn(w)
+    success(f"recorded {v.version_id}")
+    console.print(f"[dim]run log: {result.run_log.run_id}.json[/dim]")
+
+
+def _parse_status(raw: str | None) -> VersionStatus | None:
+    if raw is None:
+        return None
+    try:
+        return VersionStatus(raw.strip().upper())
+    except ValueError as exc:
+        raise DevMemoryError(
+            f"Unknown status {raw!r}.",
+            hint=f"One of: {', '.join(s.value for s in VersionStatus)}",
+        ) from exc
+
+
+def _parse_metric(raw: str) -> Metric:
+    if "=" not in raw:
+        raise DevMemoryError(f"Bad --metric {raw!r}; expected name=after or name=before:after.")
+    name, _, value = raw.partition("=")
+    name = name.strip()
+    before: float | None = None
+    if ":" in value:
+        before_s, _, after_s = value.partition(":")
+        before = _to_float(before_s, raw)
+        after = _to_float(after_s, raw)
+    else:
+        after = _to_float(value, raw)
+    direction = (
+        MetricDirection.LOWER_IS_BETTER
+        if any(h in name.lower() for h in _LOWER_IS_BETTER_HINTS)
+        else MetricDirection.HIGHER_IS_BETTER
+    )
+    return Metric(name=name, before=before, after=after, direction=direction)
+
+
+def _to_float(text: str, raw: str) -> float:
+    try:
+        return float(text.strip())
+    except ValueError as exc:
+        raise DevMemoryError(f"Bad number in --metric {raw!r}.") from exc
+
+
+__all__ = ["checkpoint_command"]

devmemory/cli/compare.py

@@ -0,0 +1,104 @@
+"""``devmemory diff`` and ``devmemory compare`` - what changed between two versions."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.table import Table
+
+from devmemory.cli._render import console, status_text
+from devmemory.services.context import ProjectContext
+from devmemory.services.versions import version_diff
+
+
+def diff_command(
+    from_ref: Annotated[str, typer.Argument(metavar="FROM", help="Base version (v6 / 6 / sha).")],
+    to_ref: Annotated[str, typer.Argument(metavar="TO", help="Target version.")],
+) -> None:
+    """Print the exact git diff between two development versions."""
+    with ProjectContext.load() as ctx:
+        result = version_diff(ctx, from_ref, to_ref)
+    console.print(
+        f"[dim]{result.from_version_id.upper()} {result.from_commit[:10]} → "
+        f"{result.to_version_id.upper()} {result.to_commit[:10]}[/dim]\n"
+    )
+    console.print(Syntax(result.diff_text or "(no changes)", "diff", theme="ansi_dark"))
+
+
+def compare_command(
+    from_ref: Annotated[str, typer.Argument(metavar="FROM")],
+    to_ref: Annotated[str, typer.Argument(metavar="TO")],
+    show_diff: Annotated[bool, typer.Option("--diff", help="Also print the git diff.")] = False,
+    as_json: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Compare two versions: files, lines, metrics, tests, status."""
+    with ProjectContext.load() as ctx:
+        result = version_diff(ctx, from_ref, to_ref)
+
+    if as_json:
+        console.print_json(json.dumps(result.model_dump(mode="json")))
+        return
+
+    console.print()
+    console.print(
+        f"[bold]{result.from_version_id.upper()}[/bold] → [bold]{result.to_version_id.upper()}[/bold]"
+        f"   {status_text(result.status_from)} → {status_text(result.status_to)}"
+    )
+    console.print(
+        f"  {result.stat.files_changed} files   "
+        f"[green]+{result.stat.additions}[/green] [red]-{result.stat.deletions}[/red]\n"
+    )
+
+    if result.files:
+        ft = Table(box=None, show_header=False, pad_edge=False)
+        ft.add_column(no_wrap=True)
+        ft.add_column(overflow="fold")
+        ft.add_column(justify="right", no_wrap=True)
+        for f in result.files:
+            mark = {
+                "added": "[green]A[/green]",
+                "modified": "[yellow]M[/yellow]",
+                "deleted": "[red]D[/red]",
+            }.get(f.change_type.value, "[cyan]" + f.change_type.value[0].upper() + "[/cyan]")
+            ft.add_row(
+                mark,
+                f.path,
+                "binary"
+                if f.binary
+                else f"[green]+{f.additions}[/green] [red]-{f.deletions}[/red]",
+            )
+        console.print(Panel(ft, title="files", title_align="left", border_style="dim"))
+
+    if result.metric_changes:
+        mt = Table(box=None, show_header=False, pad_edge=False)
+        mt.add_column(no_wrap=True)
+        mt.add_column()
+        for name, change in result.metric_changes.items():
+            before, after, delta = change["before"], change["after"], change["delta"]
+            arrow = f"{before} → {after}" if before is not None else str(after)
+            tag = ""
+            if delta is not None:
+                tag = f"  [{'green' if delta >= 0 else 'red'}]({'+' if delta >= 0 else ''}{delta:g})[/]"
+            mt.add_row(name, arrow + tag)
+        console.print(Panel(mt, title="metrics", title_align="left", border_style="dim"))
+
+    tc = result.test_changes
+    if tc.get("passed") is not None:
+        console.print(f"  tests: passed {_signed(tc['passed'])}, failed {_signed(tc['failed'])}")
+
+    if show_diff and result.diff_text:
+        console.print()
+        console.print(Syntax(result.diff_text, "diff", theme="ansi_dark"))
+
+
+def _signed(n: int | None) -> str:
+    if n is None:
+        return "?"
+    return f"+{n}" if n >= 0 else str(n)
+
+
+__all__ = ["compare_command", "diff_command"]

devmemory/cli/doctor.py

@@ -0,0 +1,151 @@
+"""``devmemory doctor`` - check the environment and the project setup.
+
+Reports credential *presence*, never values.
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import sqlite3
+import subprocess
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.table import Table
+
+from devmemory.cli._render import console
+from devmemory.config import DevMemoryConfig, resolve_databricks_credentials, resolve_llm_api_key
+from devmemory.paths import find_project_paths
+from devmemory.storage.db import Database, discover_migrations
+
+_OK = "[green]ok[/green]"
+_WARN = "[yellow]warn[/yellow]"
+_MISS = "[dim]absent[/dim]"
+
+
+def doctor_command(
+    strict: Annotated[
+        bool, typer.Option("--strict", help="Exit non-zero if any check is not ok.")
+    ] = False,
+) -> None:
+    """Diagnose the DevMemory environment: toolchain, project, storage, integrations."""
+    rows: list[tuple[str, str, str]] = []
+
+    # -- toolchain -----------------------------------------------------
+    py = platform.python_version()
+    rows.append(("python", _OK if _pyver_ok(py) else _WARN, f"{py} ({platform.system()})"))
+    rows.append(_tool("git", "git", ["--version"]))
+
+    from devmemory.adapters.graph import _find_binary as _find_graph
+
+    entire = shutil.which("entire") or _fallback("entire")
+    rows.append(
+        ("entire cli", _OK if entire else _WARN, entire or "not found (checkpoints optional)")
+    )
+    graph = _find_graph()
+    rows.append(
+        ("entire graph", _OK if graph else _MISS, graph or "not installed (impact optional)")
+    )
+
+    # -- project -----------------------------------------------------
+    paths = find_project_paths()
+    if paths is None:
+        rows.append(("project", _WARN, "no .devmemory/ here - run `devmemory init`"))
+        _render(rows)
+        raise typer.Exit(1 if strict else 0)
+
+    rows.append(("project root", _OK, str(paths.repo_root)))
+    try:
+        config = DevMemoryConfig.load(paths)
+        rows.append(("config", _OK, f"{config.project_name} ({config.project_id})"))
+    except Exception as exc:
+        rows.append(("config", _WARN, str(exc)))
+        config = None
+
+    # -- storage ---------------------------------------------------
+    try:
+        db = Database(paths.db)
+        applied = db.schema_version()
+        latest = len(discover_migrations())
+        state = _OK if applied == latest else _WARN
+        rows.append(("database", state, f"schema {applied}/{latest}"))
+        db.close()
+    except sqlite3.DatabaseError as exc:
+        rows.append(("database", _WARN, str(exc)))
+
+    outbox = list(paths.outbox_dir.glob("*.json")) if paths.outbox_dir.is_dir() else []
+    rows.append(("databricks outbox", _OK if not outbox else _WARN, f"{len(outbox)} queued"))
+
+    # -- integrations (presence only) ----------------------------
+    if config is not None:
+        rows.append(_llm_row(config))
+    dbx = resolve_databricks_credentials()
+    rows.append(
+        (
+            "databricks creds",
+            _OK if dbx else _MISS,
+            "DATABRICKS_HOST/TOKEN/WAREHOUSE_ID set" if dbx else "not set (analytics stay local)",
+        )
+    )
+
+    _render(rows)
+    if strict and any(state == _WARN for _, state, _ in rows):
+        raise typer.Exit(1)
+
+
+def _render(rows: list[tuple[str, str, str]]) -> None:
+    table = Table(show_header=False, box=None, pad_edge=False)
+    table.add_column(style="bold cyan", no_wrap=True)
+    table.add_column(no_wrap=True)
+    table.add_column(overflow="fold")
+    for name, state, detail in rows:
+        table.add_row(name, state, detail)
+    console.print()
+    console.print(table)
+
+
+def _pyver_ok(version: str) -> bool:
+    major, minor, *_ = (int(p) for p in version.split("."))
+    return (major, minor) >= (3, 11)
+
+
+def _tool(label: str, exe: str, args: list[str]) -> tuple[str, str, str]:
+    path = shutil.which(exe)
+    if path is None:
+        return (label, _WARN, "not found")
+    try:
+        out = subprocess.run(  # noqa: S603 - fixed exe, arg list, no shell
+            [path, *args], capture_output=True, text=True, timeout=5, check=False
+        )
+        first = (out.stdout or out.stderr).strip().splitlines()
+        return (label, _OK, first[0] if first else path)
+    except (OSError, subprocess.SubprocessError):
+        return (label, _WARN, "error running")
+
+
+def _fallback(name: str) -> str | None:
+    home = Path.home()
+    for candidate in (
+        home / ".local" / "bin" / name,
+        home / ".local" / "bin" / f"{name}.exe",
+        home / "AppData" / "Local" / "entire" / "plugins" / "bin" / f"{name}.exe",
+        home / ".local" / "share" / "entire" / "plugins" / "bin" / name,
+    ):
+        if candidate.is_file():
+            return str(candidate)
+    return None
+
+
+def _llm_row(config: DevMemoryConfig) -> tuple[str, str, str]:
+    configured = [p for p in config.analysis.providers if p != "rules"]
+    have = [p for p in configured if resolve_llm_api_key(p)]
+    if not configured:
+        return ("llm analysis", _OK, "rules only (no LLM configured)")
+    if have:
+        return ("llm analysis", _OK, f"key present for: {', '.join(have)}")
+    return ("llm analysis", _WARN, f"providers {configured} configured but no key in env")
+
+
+__all__ = ["doctor_command"]

devmemory/cli/history.py

@@ -0,0 +1,56 @@
+"""``devmemory history`` - the version timeline."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+from rich.table import Table
+
+from devmemory.cli._render import console, status_text
+from devmemory.services.context import ProjectContext
+from devmemory.services.versions import list_versions
+
+
+def history_command(
+    limit: Annotated[int, typer.Option("--limit", "-n", help="Most recent N versions.")] = 25,
+    as_json: Annotated[bool, typer.Option("--json", help="Emit as JSON.")] = False,
+) -> None:
+    """List development versions, newest last."""
+    with ProjectContext.load() as ctx:
+        versions = list_versions(ctx, limit=limit, ascending=False)
+    versions.reverse()
+
+    if as_json:
+        console.print_json(json.dumps([v.model_dump(mode="json") for v in versions]))
+        return
+
+    if not versions:
+        console.print("[dim]No versions yet. Run `devmemory checkpoint` after a commit.[/dim]")
+        return
+
+    table = Table(box=None, pad_edge=False, header_style="dim")
+    table.add_column("", style="bold", no_wrap=True)
+    table.add_column("status", no_wrap=True)
+    table.add_column("agent", no_wrap=True, max_width=14)
+    table.add_column("feature", no_wrap=True, max_width=18)
+    table.add_column("Δ", justify="right", no_wrap=True)
+    table.add_column("metrics", no_wrap=True, max_width=22)
+    table.add_column("intent", overflow="ellipsis", max_width=48)
+
+    for v in versions:
+        metrics = " ".join(f"{m.name}={m.after}" for m in v.metrics[:2])
+        table.add_row(
+            v.version_id.upper(),
+            status_text(v.status),
+            (v.agent or "-"),
+            (v.feature_id.split(":", 1)[-1] if v.feature_id else "-"),
+            f"[green]+{v.lines_added}[/green]/[red]-{v.lines_removed}[/red]",
+            metrics or "-",
+            v.intent or "-",
+        )
+    console.print(table)
+
+
+__all__ = ["history_command"]

devmemory/cli/impact.py

@@ -0,0 +1,95 @@
+"""``devmemory impact <version>`` - the change blast-radius for one version.
+
+Uses the Entire ``graph`` plugin. Enable it with `entire plugin install graph`
+and set `graph.enabled = true` to also collect impact during `devmemory
+checkpoint`; otherwise this command computes it on demand.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+from rich.panel import Panel
+from rich.table import Table
+
+from devmemory.cli._render import console, hint, warn
+from devmemory.services.context import ProjectContext
+from devmemory.services.impact import version_impact
+from devmemory.services.versions import get_version
+
+_CHANGE_STYLE = {
+    "removed": "bold red",
+    "signature_changed": "yellow",
+    "renamed": "cyan",
+    "added": "green",
+    "body_changed": "dim",
+}
+
+
+def impact_command(
+    version: Annotated[str, typer.Argument(help="Version ref: v7, 7, or a commit prefix.")],
+    as_json: Annotated[bool, typer.Option("--json", help="Emit as JSON.")] = False,
+    no_compute: Annotated[
+        bool,
+        typer.Option("--stored-only", help="Only show a stored result; do not run the analysis."),
+    ] = False,
+) -> None:
+    """Show the entity-level change list and dependent counts for a version."""
+    with ProjectContext.load() as ctx:
+        v = get_version(ctx, version)
+        available = ctx.graph.is_available
+        impact = version_impact(ctx, version, compute_if_missing=not no_compute)
+
+    if as_json:
+        console.print_json(json.dumps(impact.model_dump(mode="json") if impact else None))
+        return
+
+    if impact is None:
+        if not available:
+            warn("The Entire `graph` plugin is not installed.")
+            hint("Install it: entire plugin install graph")
+        else:
+            warn(f"No impact analysis available for {v.version_id.upper()}.")
+        return
+
+    console.print()
+    console.print(
+        f"[bold cyan]{v.version_id.upper()}[/bold cyan]  "
+        f"[dim]{impact.base_commit[:12]} → {impact.head_commit[:12] or 'HEAD'}[/dim]"
+    )
+    console.print(
+        f"{impact.entity_count} changed entities · max dependents {impact.max_dependents}\n"
+    )
+
+    if impact.hotspots:
+        table = Table(title="Hotspots", title_justify="left", box=None, header_style="dim")
+        table.add_column("change")
+        table.add_column("entity")
+        table.add_column("file", overflow="fold")
+        table.add_column("deps", justify="right")
+        for e in impact.hotspots:
+            style = _CHANGE_STYLE.get(e.change_type, "white")
+            table.add_row(
+                f"[{style}]{e.change_type}[/{style}]",
+                f"{e.kind} {e.name}",
+                e.path,
+                str(e.dependents_count),
+            )
+        console.print(table)
+        console.print()
+
+    risky = [e for e in impact.entities if e.is_risky]
+    if risky:
+        lines = "\n".join(
+            f"  [bold red]{e.change_type}[/bold red] {e.name} "
+            f"[dim]({e.path}, {e.dependents_count} dependents)[/dim]"
+            for e in risky
+        )
+        console.print(
+            Panel(lines, title="review before keeping", title_align="left", border_style="red")
+        )
+
+
+__all__ = ["impact_command"]