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

devmemory/cli/init.py

@@ -0,0 +1,91 @@
+"""``devmemory init`` - set DevMemory up in the current repository."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from devmemory.adapters.entire import EntireAdapter
+from devmemory.cli._render import check, console, hint, kv_table, success, warn
+from devmemory.domain.models import EntireStatus
+from devmemory.services.projects import init_project
+
+
+def init_command(
+    name: Annotated[str | None, typer.Option("--name", help="Human-readable project name.")] = None,
+    project_id: Annotated[
+        str | None,
+        typer.Option("--project-id", help="Stable slug id (default: derived from name)."),
+    ] = None,
+    force: Annotated[
+        bool, typer.Option("--force", help="Re-create configuration even if already initialized.")
+    ] = False,
+    as_json: Annotated[bool, typer.Option("--json", help="Emit the init report as JSON.")] = False,
+) -> None:
+    """Initialize DevMemory tracking in the current git repository.
+
+    Creates a `.devmemory/` directory (config, SQLite database), registers the
+    project, and reports what git and Entire look like here.
+    """
+    repo_path = Path.cwd()
+    entire = EntireAdapter(repo_path).probe()
+    report = init_project(
+        repo_path,
+        name=name,
+        project_id=project_id,
+        force=force,
+        entire_probe=entire,
+    )
+
+    if as_json:
+        console.print_json(json.dumps(report.model_dump(mode="json")))
+        return
+
+    success(f"DevMemory initialized for [bold]{report.project.name}[/bold]")
+    console.print(
+        kv_table(
+            [
+                ("project id", report.project.project_id),
+                ("repository", report.project.repo_path),
+                ("config", report.config_path),
+                ("database", report.db_path),
+                ("git", report.git_version or "detected"),
+                ("entire", _entire_line(report.entire)),
+                ("python", report.environment.python_version),
+            ]
+        )
+    )
+
+    if report.gitignore_updated:
+        console.print("[dim]added DevMemory entries to .gitignore[/dim]")
+    if not report.entire.installed:
+        warn("Entire CLI not found - versions will be recorded without checkpoint context.")
+        hint("Install Entire from https://entire.io, then run `entire enable`.")
+    elif not report.entire.enabled:
+        warn("Entire is installed but not enabled in this repository.")
+        hint("Run `entire enable` so AI sessions are captured as checkpoints.")
+
+    console.print()
+    console.print(
+        "Next: make an AI-assisted change, commit it, then run [bold]devmemory checkpoint[/bold]."
+    )
+
+
+def _entire_line(status: EntireStatus) -> object:
+    if not status.installed:
+        return check(False)
+    label = f"{status.cli_version or 'installed'}"
+    if status.enabled:
+        label += " (enabled"
+        if status.agents:
+            label += f", {', '.join(status.agents)}"
+        label += ")"
+    else:
+        label += " (not enabled)"
+    return label
+
+
+__all__ = ["init_command"]

devmemory/cli/mcp.py

@@ -0,0 +1,66 @@
+"""``devmemory mcp`` - run the Model Context Protocol server over stdio."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from devmemory.cli._render import err_console
+from devmemory.domain.errors import DevMemoryError
+from devmemory.services.context import ProjectContext
+
+
+def mcp_command(
+    repo: Annotated[
+        Path | None,
+        typer.Option("--repo", help="Repository to serve (default: discover from the cwd)."),
+    ] = None,
+    print_config: Annotated[
+        bool,
+        typer.Option(
+            "--print-config",
+            help="Print an .mcp.json fragment for this repo and exit (no server).",
+        ),
+    ] = False,
+) -> None:
+    """Expose this project's development memory to an AI agent over MCP (stdio).
+
+    Wire it into an MCP client (Claude Code, Cursor, ...) with the fragment from
+    `devmemory mcp --print-config`. The server is read-only.
+    """
+    with ProjectContext.load(repo) as ctx:
+        root = ctx.paths.repo_root
+
+    if print_config:
+        fragment = {
+            "mcpServers": {
+                "devmemory": {
+                    "command": "devmemory",
+                    "args": ["mcp", "--repo", str(root)],
+                }
+            }
+        }
+        # plain stdout, not Rich - this is meant to be copy-pasted into a JSON file
+        sys.stdout.write(json.dumps(fragment, indent=2) + "\n")
+        return
+
+    try:
+        import fastmcp  # noqa: F401
+    except ImportError as exc:  # pragma: no cover - extra not installed
+        raise DevMemoryError(
+            "the 'mcp' extra is not installed",
+            hint="pip install 'devmemory[mcp]'",
+        ) from exc
+
+    from devmemory.mcp.server import build_server
+
+    # stdio transport owns stdout; keep our chatter on stderr.
+    err_console.print(f"[dim]devmemory mcp: serving {root} over stdio[/dim]")
+    build_server(root).run(transport="stdio", show_banner=False)
+
+
+__all__ = ["mcp_command"]

devmemory/cli/memory.py

@@ -0,0 +1,70 @@
+"""``devmemory memory`` - what failed before, so it isn't tried again."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+from rich.panel import Panel
+
+from devmemory.cli._render import console, status_text
+from devmemory.services.context import ProjectContext
+from devmemory.services.memory import MemoryQuery, previous_attempts
+
+
+def memory_command(
+    files: Annotated[
+        list[str] | None,
+        typer.Option("--file", "-F", help="A path being changed (repeatable)."),
+    ] = None,
+    feature: Annotated[str | None, typer.Option("--feature", "-f", help="Feature area.")] = None,
+    intent: Annotated[
+        str | None, typer.Option("--intent", "-i", help="What you're about to do.")
+    ] = None,
+    successes: Annotated[
+        bool, typer.Option("--include-successes", help="Also show relevant successful attempts.")
+    ] = False,
+    limit: Annotated[int, typer.Option("--limit", "-n")] = 10,
+    as_json: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Show previous development attempts relevant to a change - especially failed ones."""
+    query = MemoryQuery(
+        files=list(files or []),
+        feature=feature,
+        intent=intent,
+        include_successes=successes,
+        limit=limit,
+    )
+    with ProjectContext.load() as ctx:
+        attempts = previous_attempts(ctx, query)
+
+    if as_json:
+        console.print_json(json.dumps([a.model_dump(mode="json") for a in attempts]))
+        return
+
+    if not attempts:
+        console.print("[dim]No relevant previous attempts. Nothing to avoid — yet.[/dim]")
+        return
+
+    for a in attempts:
+        head = f"[bold]{a.version_id.upper()}[/bold]  "
+        body = (
+            f"[dim]intent[/dim]   {a.intent or '—'}\n"
+            f"[dim]change[/dim]   {a.change_summary}\n"
+            f"[dim]result[/dim]   {a.result}\n"
+            f"[dim]matched[/dim]  {'; '.join(a.matched_on)}"
+        )
+        if a.recommendation:
+            body += f"\n[dim]advice[/dim]   [cyan]{a.recommendation}[/cyan]"
+        console.print(
+            Panel(
+                body,
+                title=head + str(status_text(a.status)),
+                title_align="left",
+                border_style="red" if a.is_adverse else "dim",
+            )
+        )
+
+
+__all__ = ["memory_command"]

devmemory/cli/restore.py

@@ -0,0 +1,91 @@
+"""``devmemory restore`` - move the working tree back to an earlier version, safely."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from devmemory.cli._render import console, hint, kv_table, success, warn
+from devmemory.services.context import ProjectContext
+from devmemory.services.restore import restore_preview, restore_version
+
+
+def restore_command(
+    version: Annotated[str, typer.Argument(help="Version to restore: v7 / 7 / a commit prefix.")],
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Skip the confirmation prompt.")] = False,
+    hard: Annotated[
+        bool,
+        typer.Option(
+            "--hard", help="`git reset --hard` instead of a detached checkout (requires -y)."
+        ),
+    ] = False,
+    allow_dirty: Annotated[
+        bool,
+        typer.Option(
+            "--allow-dirty", help="Proceed with uncommitted changes (a safety stash is kept)."
+        ),
+    ] = False,
+    as_json: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Restore the source tree to the git state of a previous development version.
+
+    Always previews first. A safety tag is created at the current HEAD (and a
+    ``git stash create`` reference if the tree is dirty) before anything moves.
+    """
+    with ProjectContext.load() as ctx:
+        preview = restore_preview(ctx, version)
+
+        if as_json and not yes:
+            console.print_json(json.dumps(preview.model_dump(mode="json")))
+            return
+
+        if preview.already_there:
+            success(f"Already at {preview.version_id.upper()} with a clean tree.")
+            return
+
+        console.print()
+        console.print(f"[bold]Restore {preview.version_id.upper()}[/bold]")
+        console.print(
+            kv_table(
+                [
+                    ("target", f"{preview.target_commit[:12]}  {preview.target_subject}"),
+                    (
+                        "current",
+                        f"{(preview.current_commit or '-')[:12]}"
+                        + (f" ({preview.current_branch})" if preview.current_branch else ""),
+                    ),
+                    ("mode", "reset --hard" if hard else "detached checkout"),
+                    ("safety tag", preview.safety_tag),
+                ]
+            )
+        )
+        if preview.uncommitted:
+            warn(
+                f"{len(preview.uncommitted)} uncommitted change(s): {', '.join(preview.uncommitted[:5])}"
+            )
+        console.print(f"\n[yellow]{preview.warning}[/yellow]\n")
+
+        if hard and not yes:
+            raise typer.BadParameter("--hard requires --yes")
+        if not yes and not typer.confirm("Proceed with the restore?"):
+            console.print("[dim]cancelled[/dim]")
+            raise typer.Exit(1)
+
+        result = restore_version(
+            ctx,
+            version,
+            mode="hard" if hard else "detach",
+            allow_dirty=allow_dirty,
+        )
+
+    if as_json:
+        console.print_json(json.dumps(result.model_dump(mode="json")))
+        return
+    success(result.message)
+    if result.stash_ref:
+        hint(f"uncommitted work saved as {result.stash_ref[:12]}")
+
+
+__all__ = ["restore_command"]

devmemory/cli/search.py

@@ -0,0 +1,48 @@
+"""``devmemory search`` - full-text search across development history."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from devmemory.cli._render import console, status_text
+from devmemory.services.context import ProjectContext
+from devmemory.services.versions import search_versions
+
+
+def search_command(
+    query: Annotated[
+        str, typer.Argument(help="Query: authentication, model.py, Codex, learning rate…")
+    ],
+    limit: Annotated[int, typer.Option("--limit", "-n")] = 25,
+    as_json: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Search versions by intent, agent, feature, files, commit, checkpoint, or analysis."""
+    with ProjectContext.load() as ctx:
+        results = search_versions(ctx, query, limit=limit)
+
+    if as_json:
+        console.print_json(json.dumps([v.model_dump(mode="json") for v in results]))
+        return
+
+    if not results:
+        console.print(f"[dim]No matches for “{query}”.[/dim]")
+        return
+
+    console.print()
+    for v in results:
+        console.print(
+            f"[bold]{v.version_id.upper()}[/bold]  ",
+            status_text(v.status),
+            f"  [dim]{v.feature_id.split(':')[-1] if v.feature_id else ''}[/dim]",
+        )
+        console.print(f"  {v.intent or '—'}")
+        console.print(
+            f"  [dim]{v.agent or '—'} · {v.git_commit[:12]} · "
+            f"{', '.join(f.path for f in v.changed_files[:3])}[/dim]\n"
+        )
+
+
+__all__ = ["search_command"]

devmemory/cli/serve.py

@@ -0,0 +1,64 @@
+"""``devmemory serve`` - the local dashboard + API."""
+
+from __future__ import annotations
+
+import contextlib
+import socket
+import webbrowser
+from typing import Annotated
+
+import typer
+
+from devmemory.cli._render import console, success
+from devmemory.services.context import ProjectContext
+
+
+def serve_command(
+    host: Annotated[str | None, typer.Option("--host", help="Bind address.")] = None,
+    port: Annotated[int | None, typer.Option("--port", "-p", help="Preferred port.")] = None,
+    open_browser: Annotated[
+        bool, typer.Option("--open/--no-open", help="Open the dashboard in a browser.")
+    ] = True,
+    enable_restore: Annotated[
+        bool,
+        typer.Option("--enable-restore", help="Allow the restore endpoint (off by default)."),
+    ] = False,
+    reload: Annotated[bool, typer.Option("--reload", hidden=True)] = False,
+) -> None:
+    """Start the DevMemory web dashboard on localhost."""
+    # Imported here so `fastapi`/`uvicorn` don't slow down every other command.
+    import uvicorn
+
+    from devmemory.api.app import create_app
+
+    with ProjectContext.load() as ctx:
+        repo_root = ctx.paths.repo_root
+        bind_host = host or ctx.config.web.host
+        want_port = port or ctx.config.web.port
+        allow_restore = enable_restore or ctx.config.web.enable_restore
+
+    chosen = _pick_port(bind_host, want_port)
+    url = f"http://{bind_host}:{chosen}"
+
+    app = create_app(repo_root, enable_restore=allow_restore)
+    success(f"DevMemory dashboard → [bold]{url}[/bold]")
+    console.print(f"[dim]API docs: {url}/api/docs   ·   Ctrl-C to stop[/dim]")
+    if open_browser:
+        with contextlib.suppress(Exception):
+            webbrowser.open(url)
+
+    uvicorn.run(app, host=bind_host, port=chosen, log_level="warning", reload=reload)
+
+
+def _pick_port(host: str, preferred: int) -> int:
+    for candidate in range(preferred, preferred + 20):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            try:
+                sock.bind((host, candidate))
+            except OSError:
+                continue
+            return candidate
+    return preferred
+
+
+__all__ = ["serve_command"]

devmemory/cli/show.py

@@ -0,0 +1,139 @@
+"""``devmemory show <version>`` - the full development record for one version."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+from rich.panel import Panel
+from rich.syntax import Syntax
+
+from devmemory.cli._render import console, kv_table, status_text
+from devmemory.services.context import ProjectContext
+from devmemory.services.versions import get_version
+
+
+def show_command(
+    version: Annotated[str, typer.Argument(help="Version ref: v7, 7, or a commit prefix.")],
+    diff: Annotated[bool, typer.Option("--diff", help="Also print the git diff.")] = False,
+    as_json: Annotated[bool, typer.Option("--json", help="Emit as JSON.")] = False,
+) -> None:
+    """Show one version: intent, agent, checkpoint, commit, files, tests, metrics, status."""
+    with ProjectContext.load() as ctx:
+        v = get_version(ctx, version)
+        diff_text = ctx.git.diff_text(v.parent_commit, v.git_commit) if diff else None
+
+    if as_json:
+        console.print_json(json.dumps(v.model_dump(mode="json")))
+        return
+
+    console.print()
+    console.print(f"[bold cyan]{v.version_id.upper()}[/bold cyan]  ", status_text(v.status))
+    console.print()
+
+    rows: list[tuple[str, object]] = [("intent", v.intent or "-")]
+    if v.agent:
+        rows.append(("agent", f"{v.agent}" + (f"  ({v.model})" if v.model else "")))
+    if v.primary_checkpoint:
+        cp = v.primary_checkpoint
+        line = f"{cp.checkpoint_id}  [dim]{cp.association_method.value}[/dim]"
+        if cp.is_uncertain:
+            line += f"  [yellow]confidence {cp.association_confidence:.2f}[/yellow]"
+        rows.append(("entire", line))
+    rows.append(
+        ("commit", f"{v.git_commit[:12]}  [dim](parent {(v.parent_commit or '-')[:12]})[/dim]")
+    )
+    if v.branch:
+        rows.append(("branch", v.branch))
+    if v.feature_id:
+        rows.append(("feature", v.feature_id.split(":", 1)[-1]))
+    rows.append(
+        (
+            "changes",
+            f"{v.files_changed} files   [green]+{v.lines_added}[/green] [red]-{v.lines_removed}[/red]",
+        )
+    )
+    if v.tests and v.tests.ran:
+        rows.append(
+            (
+                "tests",
+                f"{v.tests.passed} passed / {v.tests.failed} failed / {v.tests.skipped} skipped",
+            )
+        )
+    if v.artifacts:
+        a = v.artifacts[0]
+        kb = f"{a.size_bytes / 1024:.0f} KB" if a.size_bytes else "?"
+        rows.append(("snapshot", f"{a.path}  [dim]{kb}[/dim]"))
+    if v.committed_at:
+        rows.append(("committed", v.committed_at.isoformat(timespec="minutes")))
+    console.print(kv_table(rows))
+
+    if v.metrics:
+        console.print()
+        mt = kv_table(
+            (
+                m.name,
+                f"{m.before} → {m.after}"
+                + (f" {m.unit}" if m.unit else "")
+                + (
+                    "  [green]improvement[/green]"
+                    if m.is_improvement
+                    else "  [red]worse[/red]"
+                    if m.is_worse
+                    else ""
+                ),
+            )
+            for m in v.metrics
+        )
+        console.print(Panel(mt, title="metrics", title_align="left", border_style="dim"))
+
+    if v.changed_files:
+        console.print()
+        files = "\n".join(
+            f"  {_mark(f.change_type.value)} {f.path}"
+            + (
+                f"  [green]+{f.additions}[/green] [red]-{f.deletions}[/red]"
+                if not f.binary
+                else "  [dim]binary[/dim]"
+            )
+            for f in v.changed_files
+        )
+        console.print(Panel(files, title="files", title_align="left", border_style="dim"))
+
+    if v.regressions:
+        console.print()
+        for r in v.regressions:
+            console.print(f"[bold red]regression[/bold red] {r.metric or r.kind}: {r.detail}")
+
+    if v.analysis and v.analysis.summary:
+        console.print()
+        body = v.analysis.summary
+        if v.analysis.recommendation:
+            body += f"\n\n[bold]recommendation:[/bold] {v.analysis.recommendation}"
+        console.print(
+            Panel(
+                body,
+                title=f"analysis ([dim]{v.analysis.provider}[/dim])",
+                title_align="left",
+                border_style="dim",
+            )
+        )
+
+    if diff_text:
+        console.print()
+        console.print(Syntax(diff_text, "diff", theme="ansi_dark", word_wrap=False))
+
+
+def _mark(change_type: str) -> str:
+    return {
+        "added": "[green]A[/green]",
+        "modified": "[yellow]M[/yellow]",
+        "deleted": "[red]D[/red]",
+        "renamed": "[cyan]R[/cyan]",
+        "copied": "[cyan]C[/cyan]",
+        "type_changed": "[magenta]T[/magenta]",
+    }.get(change_type, "?")
+
+
+__all__ = ["show_command"]

devmemory/cli/status.py

@@ -0,0 +1,72 @@
+"""``devmemory status`` - where the project stands right now."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from devmemory.cli._render import check, console, kv_table, warn
+from devmemory.domain.models import EntireStatus
+from devmemory.services.context import ProjectContext
+from devmemory.services.projects import project_status
+
+
+def status_command(
+    as_json: Annotated[bool, typer.Option("--json", help="Emit status as JSON.")] = False,
+) -> None:
+    """Show the current project, git HEAD, working-tree cleanliness, and Entire state."""
+    with ProjectContext.load() as ctx:
+        report = project_status(ctx, entire_probe=ctx.entire.probe())
+
+    if as_json:
+        console.print_json(json.dumps(report.model_dump(mode="json")))
+        return
+
+    head = report.head_sha[:12] if report.head_sha else "(no commits yet)"
+    rows: list[tuple[str, object]] = [
+        ("project", f"{report.project.name}  [dim]({report.project.project_id})[/dim]"),
+        ("branch", report.branch or "[dim]detached[/dim]"),
+        ("HEAD", f"{head}  {report.head_subject or ''}".rstrip()),
+        ("working tree", check(report.working_tree_clean)),
+        ("versions", str(report.version_count)),
+    ]
+    if report.latest_version_id:
+        rows.append(
+            (
+                "latest",
+                f"{report.latest_version_id.upper()}  {report.latest_status}"
+                + (f"  [dim]{report.latest_intent}[/dim]" if report.latest_intent else ""),
+            )
+        )
+    if report.latest_metrics:
+        rows.append(
+            (
+                "metrics",
+                "  ".join(f"{k}={v}" for k, v in report.latest_metrics.items() if v is not None),
+            )
+        )
+    if report.open_features:
+        rows.append(("in progress", ", ".join(report.open_features)))
+    if report.last_regression_id:
+        rows.append(("last regression", report.last_regression_id.upper()))
+    rows.append(("entire", _entire_summary(report.entire)))
+    console.print(kv_table(rows))
+
+    if not report.working_tree_clean:
+        warn("uncommitted changes present")
+    if report.head_sha and not report.head_has_version:
+        warn("HEAD is not recorded yet - run `devmemory checkpoint`")
+
+
+def _entire_summary(status: EntireStatus) -> str:
+    if not status.installed:
+        return "not installed"
+    if not status.enabled:
+        return f"{status.cli_version or 'installed'}, not enabled"
+    agents = f" [{', '.join(status.agents)}]" if status.agents else ""
+    return f"{status.cli_version or 'enabled'}, enabled{agents}"
+
+
+__all__ = ["status_command"]