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

devmemory/api/schemas.py

@@ -0,0 +1,201 @@
+"""API response models. Domain models are reused where they already serialize
+cleanly; these add dashboard-shaped aggregates."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from devmemory.domain.models import ChangedFile, DiffStat
+
+
+class ProjectSummary(BaseModel):
+    project_id: str
+    name: str
+    repo_path: str
+    branch: str | None
+    head_sha: str | None
+    head_subject: str | None
+    working_tree_clean: bool
+    version_count: int
+    latest_version_id: str | None
+    latest_status: str | None
+    latest_intent: str | None
+    head_has_version: bool
+    last_regression_id: str | None
+    open_features: list[str]
+    latest_metrics: dict[str, float | None]
+    entire_installed: bool
+    entire_enabled: bool
+    entire_version: str | None
+    entire_agents: list[str]
+
+
+class VersionListItem(BaseModel):
+    version_id: str
+    version_number: int
+    status: str
+    intent: str | None
+    agent: str | None
+    model: str | None
+    feature: str | None
+    git_commit: str
+    branch: str | None
+    files_changed: int
+    lines_added: int
+    lines_removed: int
+    checkpoint_id: str | None
+    association_method: str
+    association_confidence: float
+    metrics: dict[str, float | None]
+    tests_passed: int | None
+    tests_failed: int | None
+    has_regression: bool
+    committed_at: str | None
+    created_at: str
+
+
+class MetricChange(BaseModel):
+    name: str
+    before: float | None
+    after: float | None
+    delta: float | None
+    unit: str | None
+    direction: str
+
+
+class ComparisonResponse(BaseModel):
+    from_version: str
+    to_version: str
+    from_commit: str
+    to_commit: str
+    stat: DiffStat
+    files: list[ChangedFile]
+    diff_text: str
+    metric_changes: list[MetricChange]
+    test_changes: dict[str, int | None]
+    status_from: str
+    status_to: str
+    feature_from: str | None = None
+    feature_to: str | None = None
+    checkpoint_from: str | None = None
+    checkpoint_to: str | None = None
+
+
+class FeatureHistoryPoint(BaseModel):
+    version_id: str
+    version_number: int
+    status: str
+    metrics: dict[str, float | None]
+    committed_at: str | None
+
+
+class FeatureDetail(BaseModel):
+    feature_id: str
+    name: str
+    status: str
+    derived_from: str | None
+    version_count: int
+    latest_metrics: dict[str, float | None]
+    history: list[FeatureHistoryPoint]
+
+
+class SearchHit(BaseModel):
+    version_id: str
+    version_number: int
+    status: str
+    intent: str | None
+    agent: str | None
+    feature: str | None
+    git_commit: str
+    snippet: str | None = None
+
+
+class SearchResponse(BaseModel):
+    query: str
+    count: int
+    results: list[SearchHit]
+
+
+class AgentCheckRequest(BaseModel):
+    """Body for ``POST /api/agent/check`` - the pre-flight risk read."""
+
+    files: list[str] = []
+    intent: str | None = None
+    feature: str | None = None
+
+
+# --- state-aware coding loop ---------------------------------------------------
+
+
+class TaskCreateRequest(BaseModel):
+    goal: str
+    test_command: str | None = None
+
+
+class IssueRequest(BaseModel):
+    description: str
+    blocking: bool = False
+
+
+class RequirementUpdateRequest(BaseModel):
+    status: str
+    note: str = ""
+
+
+class TaskSummary(BaseModel):
+    """One row in the tasks list."""
+
+    id: str
+    goal: str
+    status: str
+    branch: str
+    requirements_total: int
+    requirements_complete: int
+    test_command: str | None
+    updated_at: str | None
+
+
+class SnapshotSummary(BaseModel):
+    """One point on a task's state timeline (the full state stays server-side)."""
+
+    id: int | None
+    overall_status: str
+    commit_sha: str | None
+    checkpoint_id: str | None
+    tests_passed: int
+    tests_failed: int
+    tests_status: str
+    requirements_total: int
+    requirements_complete: int
+    created_at: str | None
+
+
+class ProjectBriefDoc(BaseModel):
+    """The project's single source of truth: one editable markdown document."""
+
+    content: str
+    updated_at: str | None
+
+
+class ProjectBriefRequest(BaseModel):
+    content: str
+
+
+__all__ = [
+    "AgentCheckRequest",
+    "ComparisonResponse",
+    "FeatureDetail",
+    "FeatureHistoryPoint",
+    "IssueRequest",
+    "MetricChange",
+    "ProjectBriefDoc",
+    "ProjectBriefRequest",
+    "ProjectSummary",
+    "RequirementUpdateRequest",
+    "SearchHit",
+    "SearchResponse",
+    "SnapshotSummary",
+    "TaskCreateRequest",
+    "TaskSummary",
+    "VersionListItem",
+]

devmemory/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface. A thin Typer layer over ``devmemory`` services."""

devmemory/cli/_errors.py

@@ -0,0 +1,36 @@
+"""Turn :class:`DevMemoryError` into a clean CLI message + hint + exit code.
+
+Applied to every command at registration so ``CliRunner`` (which invokes the
+Typer app directly, not ``main()``) still sees the right exit status.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
+
+import typer
+
+from devmemory.cli._render import err_console
+from devmemory.domain.errors import DevMemoryError
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+def handle_errors(func: Callable[_P, _R]) -> Callable[_P, _R]:
+    @functools.wraps(func)
+    def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+        try:
+            return func(*args, **kwargs)
+        except DevMemoryError as exc:
+            err_console.print(f"[bold red]error:[/bold red] {exc.message}")
+            if exc.hint:
+                err_console.print(f"[dim]hint:[/dim] {exc.hint}")
+            raise typer.Exit(code=exc.exit_code) from exc
+
+    return wrapper
+
+
+__all__ = ["handle_errors"]

devmemory/cli/_render.py

@@ -0,0 +1,79 @@
+"""Shared Rich rendering helpers for the CLI."""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+from collections.abc import Iterable
+
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from devmemory.domain.enums import VersionStatus
+
+
+def _force_utf8() -> None:
+    """Windows consoles default to cp1252; make our Unicode output survive pipes."""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if callable(reconfigure):
+            with contextlib.suppress(ValueError, OSError):
+                reconfigure(encoding="utf-8", errors="replace")
+
+
+_force_utf8()
+
+console = Console(soft_wrap=False)
+err_console = Console(stderr=True, soft_wrap=False)
+
+_STATUS_STYLE: dict[str, str] = {
+    VersionStatus.SUCCESS: "bold green",
+    VersionStatus.PARTIAL_SUCCESS: "yellow",
+    VersionStatus.ERROR: "bold red",
+    VersionStatus.REGRESSION: "bold red",
+    VersionStatus.IN_PROGRESS: "cyan",
+    VersionStatus.NEEDS_REVIEW: "dim",
+}
+
+
+def status_text(status: str | VersionStatus) -> Text:
+    key = str(status)
+    return Text(key, style=_STATUS_STYLE.get(key, "white"))
+
+
+def check(ok: bool) -> Text:
+    return Text("yes", style="green") if ok else Text("no", style="red")
+
+
+def kv_table(rows: Iterable[tuple[str, object]], *, title: str | None = None) -> Table:
+    table = Table(show_header=False, box=None, pad_edge=False, title=title, title_justify="left")
+    table.add_column(style="bold cyan", no_wrap=True)
+    table.add_column(overflow="fold")
+    for key, value in rows:
+        table.add_row(key, value if isinstance(value, Text) else str(value))
+    return table
+
+
+def hint(text: str) -> None:
+    console.print(f"[dim]hint:[/dim] {text}")
+
+
+def success(text: str) -> None:
+    console.print(f"[bold green]✓[/bold green] {text}")
+
+
+def warn(text: str) -> None:
+    console.print(f"[yellow]![/yellow] {text}")
+
+
+__all__ = [
+    "check",
+    "console",
+    "err_console",
+    "hint",
+    "kv_table",
+    "status_text",
+    "success",
+    "warn",
+]

devmemory/cli/analytics.py

@@ -0,0 +1,136 @@
+"""``devmemory analytics`` and ``devmemory databricks``."""
+
+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, success, warn
+from devmemory.services.analytics import analytics_summary
+from devmemory.services.context import ProjectContext
+from devmemory.services.databricks_sync import drain, sync_status
+
+
+def analytics_command(
+    as_json: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Development intelligence: regressions, feature attempts, file churn, agents, trend."""
+    with ProjectContext.load() as ctx:
+        summary = analytics_summary(ctx)
+
+    if as_json:
+        console.print_json(json.dumps(summary.model_dump(mode="json")))
+        return
+
+    console.print()
+    console.print(
+        f"[bold]{summary.project}[/bold]   "
+        f"[dim]source: {summary.source}[/dim]   "
+        f"{summary.version_count} versions · {summary.regression_count} regressions · "
+        f"{summary.success_rate}% success\n"
+    )
+
+    if summary.regressions:
+        t = Table(title="Regressions", title_justify="left", box=None, header_style="dim")
+        t.add_column("")
+        t.add_column("sev")
+        t.add_column("feature")
+        t.add_column("detail", overflow="fold")
+        for r in summary.regressions[:10]:
+            t.add_row(r.version_id.upper(), r.severity, r.feature or "-", r.detail)
+        console.print(t)
+        console.print()
+
+    if summary.features:
+        t = Table(title="Feature attempts", title_justify="left", box=None, header_style="dim")
+        t.add_column("feature")
+        t.add_column("attempts", justify="right")
+        t.add_column("success", justify="right")
+        t.add_column("regressions", justify="right")
+        for feat in summary.features:
+            t.add_row(
+                feat.feature, str(feat.attempts), f"{feat.success_rate}%", str(feat.regressions)
+            )
+        console.print(t)
+        console.print()
+
+    if summary.file_churn:
+        t = Table(title="File churn", title_justify="left", box=None, header_style="dim")
+        t.add_column("file")
+        t.add_column("changes", justify="right")
+        t.add_column("adverse", justify="right")
+        for churn in summary.file_churn[:10]:
+            t.add_row(churn.path, str(churn.changes), str(churn.adverse_changes))
+        console.print(t)
+        console.print()
+
+    if summary.agents:
+        t = Table(title="Agent effectiveness", title_justify="left", box=None, header_style="dim")
+        t.add_column("agent")
+        t.add_column("versions", justify="right")
+        t.add_column("success", justify="right")
+        t.add_column("tokens/success", justify="right")
+        for row in summary.agents:
+            t.add_row(
+                row.agent,
+                str(row.versions),
+                f"{row.success_rate}%",
+                f"{row.tokens_per_success / 1000:.0f}k" if row.tokens_per_success else "-",
+            )
+        console.print(t)
+
+    if summary.failed_approaches:
+        console.print()
+        for fa in summary.failed_approaches[:5]:
+            console.print(
+                f"[red]repeatedly failed[/red] ({fa.occurrences}x) "
+                f"{', '.join(fa.signature[:3])}  [dim]{fa.example_intent or ''}[/dim]"
+            )
+
+
+databricks_app = typer.Typer(help="Databricks analytics sync.", no_args_is_help=True)
+
+
+@databricks_app.command("status")
+def databricks_status() -> None:
+    """Show Databricks configuration and the pending outbox."""
+    with ProjectContext.load() as ctx:
+        s = sync_status(ctx)
+    console.print(
+        f"configured: {s.configured}\n"
+        f"detail: {s.detail}\n"
+        f"queued: {len(s.queued)}"
+        + (f" ({', '.join(x.upper() for x in s.queued)})" if s.queued else "")
+    )
+    if not s.configured:
+        hint(
+            "Set DATABRICKS_HOST, DATABRICKS_TOKEN, DATABRICKS_WAREHOUSE_ID, then `devmemory databricks push`."
+        )
+
+
+@databricks_app.command("push")
+def databricks_push() -> None:
+    """Publish every queued development version to Databricks."""
+    with ProjectContext.load() as ctx:
+        result = drain(ctx)
+    if not result.configured:
+        warn(result.detail or "Databricks is not configured.")
+        return
+    if result.pushed:
+        success(f"published {len(result.pushed)}: {', '.join(x.upper() for x in result.pushed)}")
+    if result.failed:
+        warn(f"failed: {', '.join(result.failed)} — {result.detail}")
+    if not result.pushed and not result.failed:
+        if result.detail:
+            warn(result.detail)
+        else:
+            console.print("[dim]nothing queued[/dim]")
+    if result.queued:
+        console.print(Panel(", ".join(x.upper() for x in result.queued), title="still queued"))
+
+
+__all__ = ["analytics_command", "databricks_app"]

devmemory/cli/analyze.py

@@ -0,0 +1,58 @@
+"""``devmemory analyze <version>`` - (re)generate the AI analysis for a version."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+from rich.panel import Panel
+
+from devmemory.cli._render import console, warn
+from devmemory.services.analysis import analyze_version
+from devmemory.services.context import ProjectContext
+
+_RISK_STYLE = {"low": "green", "medium": "yellow", "high": "bold red"}
+
+
+def analyze_command(
+    version: Annotated[str, typer.Argument(help="Version ref: v7, 7, or a commit prefix.")],
+    provider: Annotated[
+        list[str] | None,
+        typer.Option("--provider", "-p", help="Override the provider chain (repeatable)."),
+    ] = None,
+    no_save: Annotated[
+        bool, typer.Option("--no-save", help="Print the analysis without storing it.")
+    ] = False,
+    as_json: Annotated[bool, typer.Option("--json", help="Emit as JSON.")] = False,
+) -> None:
+    """Run the analysis provider chain for a version. Interpretation only - it can
+    never change the recorded facts."""
+    with ProjectContext.load() as ctx:
+        analysis = analyze_version(ctx, version, providers=provider or None, persist=not no_save)
+
+    if as_json:
+        console.print_json(json.dumps(analysis.model_dump(mode="json")))
+        return
+
+    risk = (analysis.risk or "unknown").lower()
+    console.print()
+    console.print(
+        f"[bold cyan]{version.upper()}[/bold cyan]  "
+        f"[dim]{analysis.provider}"
+        f"{f' · {analysis.model}' if analysis.model else ''}[/dim]  "
+        f"risk [{_RISK_STYLE.get(risk, 'white')}]{risk}[/{_RISK_STYLE.get(risk, 'white')}]"
+    )
+    console.print()
+    console.print(Panel(analysis.summary or "(no summary)", title="summary", title_align="left"))
+    if analysis.reasoning:
+        console.print(f"\n[dim]reasoning:[/dim] {analysis.reasoning}")
+    if analysis.recommendation:
+        console.print(f"\n[bold]recommendation:[/bold] {analysis.recommendation}")
+    for w in analysis.warnings:
+        console.print(f"[yellow]![/yellow] {w}")
+    if no_save:
+        warn("not saved (--no-save)")
+
+
+__all__ = ["analyze_command"]

devmemory/cli/app.py

@@ -0,0 +1,163 @@
+"""The ``devmemory`` / ``dm`` entry point.
+
+Thin Typer layer: each command lives in its own module and is registered here.
+Top-level error handling turns :class:`DevMemoryError` into a clean message +
+hint + exit code.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+from typing import Annotated
+
+import typer
+from rich.table import Table
+
+from devmemory.__about__ import __version__
+from devmemory.cli._errors import handle_errors
+from devmemory.cli._render import console, err_console
+from devmemory.cli.analytics import analytics_command, databricks_app
+from devmemory.cli.analyze import analyze_command
+from devmemory.cli.checkpoint import checkpoint_command
+from devmemory.cli.compare import compare_command, diff_command
+from devmemory.cli.doctor import doctor_command
+from devmemory.cli.history import history_command
+from devmemory.cli.impact import impact_command
+from devmemory.cli.init import init_command
+from devmemory.cli.mcp import mcp_command
+from devmemory.cli.memory import memory_command
+from devmemory.cli.restore import restore_command
+from devmemory.cli.search import search_command
+from devmemory.cli.serve import serve_command
+from devmemory.cli.show import show_command
+from devmemory.cli.status import status_command
+from devmemory.cli.task import state_command, task_app
+from devmemory.domain.errors import DevMemoryError
+from devmemory.logging import configure_logging
+
+app = typer.Typer(
+    name="devmemory",
+    help=(
+        "DevMemory - development-memory and version-intelligence for AI-assisted "
+        "software development.\n\n"
+        "Git remembers what changed. Entire remembers the AI-assisted context. "
+        "DevMemory connects them with results, so you and the next agent can see "
+        "the whole story."
+    ),
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        console.print(f"devmemory {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    _version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_print_version,
+            is_eager=True,
+            help="Show the DevMemory version and exit.",
+        ),
+    ] = False,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Show info-level diagnostic logs.")
+    ] = False,
+) -> None:
+    """DevMemory command-line interface."""
+    _load_dotenv()
+    level = os.environ.get("DEVMEMORY_LOG_LEVEL") or ("INFO" if verbose else "WARNING")
+    configure_logging(level=level, json_logs=False)
+
+
+def _load_dotenv() -> None:
+    """Load a ``.env`` (searched from the cwd upward) so credentials can live in a
+    file. Real environment variables always win - ``.env`` never overrides them."""
+    from dotenv import find_dotenv, load_dotenv
+
+    found = find_dotenv(usecwd=True)
+    if found:
+        load_dotenv(found, override=False)
+
+
+def _tool_version(executable: str, args: list[str]) -> str:
+    path = shutil.which(executable)
+    if path is None:
+        return "[dim]not found[/dim]"
+    try:
+        result = subprocess.run(  # noqa: S603 - fixed executable, no shell
+            [path, *args],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return "[yellow]error[/yellow]"
+    output = (result.stdout or result.stderr).strip().splitlines()
+    return output[0].strip() if output else "[green]present[/green]"
+
+
+@app.command()
+def version() -> None:
+    """Show the DevMemory version and the toolchain it detects."""
+    table = Table(show_header=False, box=None, pad_edge=False)
+    table.add_column(style="bold cyan")
+    table.add_column()
+    table.add_row("DevMemory", __version__)
+    table.add_row("Python", platform.python_version())
+    table.add_row("Platform", f"{platform.system()} {platform.release()} ({platform.machine()})")
+    table.add_row("git", _tool_version("git", ["--version"]))
+    table.add_row("entire", _tool_version("entire", ["version"]))
+    console.print(table)
+
+
+app.command(name="init")(handle_errors(init_command))
+app.command(name="doctor")(handle_errors(doctor_command))
+app.command(name="status")(handle_errors(status_command))
+app.command(name="checkpoint")(handle_errors(checkpoint_command))
+app.command(name="history")(handle_errors(history_command))
+app.command(name="show")(handle_errors(show_command))
+app.command(name="diff")(handle_errors(diff_command))
+app.command(name="compare")(handle_errors(compare_command))
+app.command(name="impact")(handle_errors(impact_command))
+app.command(name="analyze")(handle_errors(analyze_command))
+app.command(name="search")(handle_errors(search_command))
+app.command(name="memory")(handle_errors(memory_command))
+app.command(name="restore")(handle_errors(restore_command))
+app.command(name="analytics")(handle_errors(analytics_command))
+app.add_typer(databricks_app, name="databricks")
+app.command(name="serve")(handle_errors(serve_command))
+app.command(name="mcp")(handle_errors(mcp_command))
+app.add_typer(task_app, name="task")
+app.command(name="state")(handle_errors(state_command))
+
+
+def main() -> None:
+    """Console-script entry point with top-level error handling."""
+    try:
+        app()
+    except DevMemoryError as exc:
+        err_console.print(f"[bold red]error:[/bold red] {exc.message}")
+        if exc.hint:
+            err_console.print(f"[dim]hint:[/dim] {exc.hint}")
+        raise SystemExit(exc.exit_code) from exc
+    except KeyboardInterrupt:  # pragma: no cover
+        err_console.print("[dim]interrupted[/dim]")
+        raise SystemExit(130) from None
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()