agent-brain-cli 10.0.3__tar.gz → 10.0.5__tar.gz

{agent_brain_cli-10.0.3 → agent_brain_cli-10.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: agent-brain-cli
-Version: 10.0.3
+Version: 10.0.5
 Summary: Agent Brain CLI - Command-line interface for managing AI agent memory and knowledge retrieval
 Home-page: https://github.com/SpillwaveSolutions/agent-brain
 License: MIT
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: agent-brain-rag (>=10.0.3,<11.0.0)
+Requires-Dist: agent-brain-rag (>=10.0.5,<11.0.0)
 Requires-Dist: click (>=8.1.0,<9.0.0)
 Requires-Dist: httpx (>=0.28.0,<0.29.0)
 Requires-Dist: pydantic (>=2.10.0,<3.0.0)

{agent_brain_cli-10.0.3 → agent_brain_cli-10.0.5}/agent_brain_cli/__init__.py

@@ -1,3 +1,3 @@
 """Doc-Serve CLI - Command-line interface for managing Doc-Serve server."""
 
-__version__ = "10.0.3"
+__version__ = "10.0.5"

{agent_brain_cli-10.0.3 → agent_brain_cli-10.0.5}/agent_brain_cli/commands/doctor.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import json
+
 import click
 from rich.console import Console
 from rich.panel import Panel
@@ -11,6 +13,7 @@ from agent_brain_cli.diagnostics import (
     SEVERITY_FAIL,
     SEVERITY_OK,
     SEVERITY_WARN,
+    apply_safe_fixes,
     report_to_json,
     run_doctor,
 )
@@ -33,18 +36,40 @@ _STATUS_STYLE = {
     help="Server URL to probe (default: resolved from runtime.json or config).",
 )
 @click.option("--json", "json_output", is_flag=True, help="Emit machine-readable JSON.")
-def doctor_command(url: str | None, json_output: bool) -> None:
+@click.option(
+    "--fix",
+    "apply_fixes",
+    is_flag=True,
+    help=(
+        "Apply safe, idempotent, offline fixes (add .agent-brain/ to .gitignore, "
+        "create state dir + stub config.json). Will not touch API keys, network, "
+        "or user code. Re-runs the report after fixing."
+    ),
+)
+def doctor_command(url: str | None, json_output: bool, apply_fixes: bool) -> None:
     """Diagnose your Agent Brain setup.
 
     Inspects Python version, project init state, provider config, required
     API keys, optional dependencies, .gitignore hygiene, and whether the
     server is reachable. Exits non-zero on any critical failure so it can
     be used in scripts (``agent-brain doctor || agent-brain init``).
+
+    Pass ``--fix`` to auto-apply the safe subset of remediations and re-run.
     """
     report = run_doctor(server_url_override=url)
 
+    fix_actions: list[str] = []
+    if apply_fixes:
+        fix_actions = apply_safe_fixes(report)
+        if fix_actions:
+            # Re-run so the printed report reflects the fixed state.
+            report = run_doctor(server_url_override=url)
+
     if json_output:
-        click.echo(report_to_json(report))
+        payload = json.loads(report_to_json(report))
+        if apply_fixes:
+            payload["applied_fixes"] = fix_actions
+        click.echo(json.dumps(payload, indent=2))
         raise SystemExit(report.exit_code)
 
     header_color = "green" if report.exit_code == 0 else "red"
@@ -75,6 +100,17 @@ def doctor_command(url: str | None, json_output: bool) -> None:
 
     console.print(table)
 
+    if apply_fixes:
+        if fix_actions:
+            console.print("\n[cyan]Applied safe fixes:[/]")
+            for action in fix_actions:
+                console.print(f"  • {action}")
+        else:
+            console.print(
+                "\n[dim]No safe fixes applied (nothing actionable, or all "
+                "checks already passing).[/]"
+            )
+
     if report.exit_code != 0:
         console.print(
             "\n[red]Doctor reported critical issues.[/] "

{agent_brain_cli-10.0.3 → agent_brain_cli-10.0.5}/agent_brain_cli/commands/jobs.py

@@ -25,13 +25,32 @@ def _format_timestamp(ts: str | None) -> str:
     return ts
 
 
-def _format_progress(progress: float | None, total: int | None) -> str:
-    """Format progress for display."""
+def _format_progress(
+    progress: float | int | dict[str, Any] | None,
+    total: int | None,
+) -> str:
+    """Format progress for display.
+
+    Copes with both the legacy float shape and the structured ``JobProgress``
+    dict the server emits today (#150). Falls back to a string coercion for
+    unknown types so the CLI never raises.
+    """
     if progress is None:
         return "-"
-    if total:
-        return f"{progress:.1f}% ({total} files)"
-    return f"{progress:.1f}%"
+    if isinstance(progress, dict):
+        pct = progress.get("percent_complete")
+        if isinstance(pct, (int, float)):
+            files_total = progress.get("files_total") or 0
+            files_done = progress.get("files_processed") or 0
+            if files_total:
+                return f"{pct:.1f}% ({files_done}/{files_total} files)"
+            return f"{pct:.1f}%"
+        return ", ".join(f"{k}={v}" for k, v in progress.items())
+    if isinstance(progress, (int, float)):
+        if total:
+            return f"{progress:.1f}% ({total} files)"
+        return f"{progress:.1f}%"
+    return str(progress)
 
 
 def _get_status_style(status: str) -> str:
@@ -121,12 +140,17 @@ def _create_job_detail_panel(job: dict[str, Any]) -> Panel:
     if (progress := job.get("progress_percent", job.get("progress"))) is not None:
         total = job.get("total_files", 0)
         processed = job.get("processed_files", 0)
-        if total:
+        # #150: server emits structured JobProgress dicts in addition to floats.
+        # Defer formatting to _format_progress so list-view and detail-view
+        # never diverge on type handling.
+        if isinstance(progress, (int, float)) and total:
             lines.append(
                 f"[bold]Progress:[/] {progress:.1f}% ({processed}/{total} files)"
             )
         else:
-            lines.append(f"[bold]Progress:[/] {progress:.1f}%")
+            lines.append(
+                f"[bold]Progress:[/] {_format_progress(progress, total or None)}"
+            )
 
     if enqueued := job.get("enqueued_at", job.get("created_at")):
         lines.append(f"[bold]Enqueued:[/] {_format_timestamp(enqueued)}")

{agent_brain_cli-10.0.3 → agent_brain_cli-10.0.5}/agent_brain_cli/commands/stop.py

@@ -3,7 +3,6 @@
 import json
 import os
 import signal
-import subprocess
 import time
 from pathlib import Path
 from typing import Any
@@ -12,6 +11,7 @@ from urllib.request import Request, urlopen
 import click
 from rich.console import Console
 
+from agent_brain_cli.config import resolve_project_root
 from agent_brain_cli.migration import resolve_state_dir_with_fallback
 from agent_brain_cli.xdg_paths import get_registry_path
 
@@ -23,38 +23,6 @@ PID_FILE = "agent-brain.pid"
 RUNTIME_FILE = "runtime.json"
 
 
-def resolve_project_root(start_path: Path | None = None) -> Path:
-    """Resolve the canonical project root directory."""
-    start = (start_path or Path.cwd()).resolve()
-
-    # Try git root first
-    try:
-        result = subprocess.run(
-            ["git", "rev-parse", "--show-toplevel"],
-            capture_output=True,
-            text=True,
-            timeout=5,
-            cwd=str(start),
-        )
-        if result.returncode == 0:
-            return Path(result.stdout.strip()).resolve()
-    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
-        pass
-
-    # Walk up looking for markers
-    current = start
-    while current != current.parent:
-        if (current / ".agent-brain").is_dir():
-            return current
-        if (current / ".claude").is_dir():
-            return current
-        if (current / "pyproject.toml").is_file():
-            return current
-        current = current.parent
-
-    return start
-
-
 def read_runtime(state_dir: Path) -> dict[str, Any] | None:
     """Read runtime state from state directory."""
     runtime_path = state_dir / RUNTIME_FILE

{agent_brain_cli-10.0.3 → agent_brain_cli-10.0.5}/agent_brain_cli/config.py

@@ -254,6 +254,20 @@ def load_config(start_path: Path | None = None) -> AgentBrainConfig:
 def resolve_project_root(start_path: Path | None = None) -> Path:
     """Find the project root by looking for markers.
 
+    Thin wrapper around :func:`resolve_project_root_with_strategy` that drops
+    the strategy label for callers that only need the path.
+    """
+    return resolve_project_root_with_strategy(start_path)[0]
+
+
+def resolve_project_root_with_strategy(
+    start_path: Path | None = None,
+) -> tuple[Path, str]:
+    """Find the project root and report *which* rule matched.
+
+    Used by ``agent-brain doctor`` to explain why a given directory was
+    selected (issue #146).
+
     Resolution order (first match wins):
     1. Walk up from ``start_path`` looking for ``.agent-brain/`` — this lets a
        sub-project inside a mono-repo keep its own state dir and not get
@@ -263,11 +277,10 @@ def resolve_project_root(start_path: Path | None = None) -> Path:
     4. Walk up looking for ``.claude/`` or ``pyproject.toml``.
     5. Fall back to ``start_path``.
 
-    Args:
-        start_path: Starting directory. Defaults to cwd.
-
     Returns:
-        Project root path.
+        ``(root, strategy)`` where ``strategy`` is one of
+        ``"agent_brain_dir"``, ``"legacy_claude_dir"``, ``"git_root"``,
+        ``"claude_dir"``, ``"pyproject"``, ``"cwd_fallback"``.
     """
     import subprocess
 
@@ -277,9 +290,9 @@ def resolve_project_root(start_path: Path | None = None) -> Path:
     current = start
     while current != current.parent:
         if (current / STATE_DIR_NAME).is_dir():
-            return current
+            return current, "agent_brain_dir"
         if (current / LEGACY_STATE_DIR_NAME).is_dir():
-            return current
+            return current, "legacy_claude_dir"
         current = current.parent
 
     # 3. Git root next — useful when this is the first time the user runs init.
@@ -292,7 +305,7 @@ def resolve_project_root(start_path: Path | None = None) -> Path:
             cwd=str(start),
         )
         if result.returncode == 0:
-            return Path(result.stdout.strip()).resolve()
+            return Path(result.stdout.strip()).resolve(), "git_root"
     except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
         pass
 
@@ -300,12 +313,12 @@ def resolve_project_root(start_path: Path | None = None) -> Path:
     current = start
     while current != current.parent:
         if (current / ".claude").is_dir():
-            return current
+            return current, "claude_dir"
         if (current / "pyproject.toml").is_file():
-            return current
+            return current, "pyproject"
         current = current.parent
 
-    return start
+    return start, "cwd_fallback"
 
 
 # Backwards-compatible alias for any external callers.

{agent_brain_cli-10.0.3 → agent_brain_cli-10.0.5}/agent_brain_cli/diagnostics.py

@@ -26,6 +26,7 @@ from agent_brain_cli.config import (
     get_server_url,
     load_config,
     resolve_project_root,
+    resolve_project_root_with_strategy,
 )
 
 #: Severity returned by every diagnostic check.
@@ -69,6 +70,49 @@ class DoctorReport:
         return data
 
 
+_RESOLVE_STRATEGY_LABEL: dict[str, str] = {
+    "agent_brain_dir": f"found {STATE_DIR_NAME}/ in this dir or an ancestor",
+    "legacy_claude_dir": f"found legacy {LEGACY_STATE_DIR_NAME}/",
+    "git_root": "git repository root (no state dir present yet)",
+    "claude_dir": ".claude/ marker in this dir or an ancestor",
+    "pyproject": "pyproject.toml marker in this dir or an ancestor",
+    "cwd_fallback": "no markers found — falling back to cwd",
+}
+
+
+def _check_version() -> CheckResult:
+    """Confirm the installed agent-brain-cli is importable and report version.
+
+    Issue #146 check #2 — surfaces broken installs (missing entry-point,
+    namespace shadowing, half-rolled-back upgrades) at the top of the doctor
+    report instead of leaving the user to discover them later.
+    """
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+
+        ver = version("agent-brain-cli")
+    except PackageNotFoundError as exc:
+        return CheckResult(
+            "cli_version",
+            SEVERITY_FAIL,
+            "agent-brain-cli is not installed in this Python environment.",
+            fix="pip install agent-brain-cli  (or uv tool install agent-brain-cli)",
+            details={"error": str(exc)},
+        )
+    except Exception as exc:  # noqa: BLE001
+        return CheckResult(
+            "cli_version",
+            SEVERITY_FAIL,
+            f"Could not determine agent-brain-cli version: {exc}",
+        )
+    return CheckResult(
+        "cli_version",
+        SEVERITY_OK,
+        f"agent-brain-cli {ver}",
+        details={"version": ver},
+    )
+
+
 def _check_python() -> CheckResult:
     major, minor = sys.version_info[:2]
     version = f"{major}.{minor}.{sys.version_info.micro}"
@@ -88,23 +132,35 @@ def _check_python() -> CheckResult:
     )
 
 
-def _check_project_init(project_root: Path, state_dir: Path) -> CheckResult:
+def _check_project_init(
+    project_root: Path, state_dir: Path, resolved_via: str
+) -> CheckResult:
+    """Validate the resolved project root and explain *why* it was picked.
+
+    Issue #146 check #3 — operators on monorepos / nested projects can be
+    surprised by which directory wins; the strategy label tells them.
+    """
+    strategy_msg = _RESOLVE_STRATEGY_LABEL.get(resolved_via, resolved_via)
     config_path = state_dir / "config.json"
     if config_path.exists():
         return CheckResult(
             "project_initialized",
             SEVERITY_OK,
-            f"Project initialized at {state_dir}",
-            details={"state_dir": str(state_dir)},
+            f"Project initialized at {state_dir} ({strategy_msg})",
+            details={
+                "state_dir": str(state_dir),
+                "resolved_via": resolved_via,
+            },
         )
     return CheckResult(
         "project_initialized",
         SEVERITY_FAIL,
-        f"No {STATE_DIR_NAME}/config.json under {project_root}",
+        (f"No {STATE_DIR_NAME}/config.json under {project_root} " f"({strategy_msg})"),
         fix="Run `agent-brain init` in your project directory.",
         details={
             "project_root": str(project_root),
             "expected_path": str(config_path),
+            "resolved_via": resolved_via,
         },
     )
 
@@ -223,11 +279,21 @@ def _check_server(server_url: str, runtime_file: Path | None) -> CheckResult:
         req = Request(server_url.rstrip("/") + "/health")
         with urlopen(req, timeout=3) as resp:  # noqa: S310 — local URL
             body = resp.read().decode("utf-8", errors="replace")
+        # Issue #146 check #7 — also pull /health/status for the richer
+        # indexing summary. Tolerate older servers that 404 here.
+        indexing_summary, indexing_payload = _fetch_indexing_summary(server_url)
+        message = f"Server responded at {server_url}"
+        if indexing_summary:
+            message = f"{message} — {indexing_summary}"
         return CheckResult(
             "server_reachable",
             SEVERITY_OK,
-            f"Server responded at {server_url}",
-            details={"server_url": server_url, "response_preview": body[:120]},
+            message,
+            details={
+                "server_url": server_url,
+                "response_preview": body[:120],
+                "indexing": indexing_payload,
+            },
         )
     except URLError as exc:
         return CheckResult(
@@ -247,6 +313,30 @@ def _check_server(server_url: str, runtime_file: Path | None) -> CheckResult:
         )
 
 
+def _fetch_indexing_summary(
+    server_url: str,
+) -> tuple[str | None, dict[str, Any] | None]:
+    """Best-effort fetch of /health/status, returning (one-line summary, raw)."""
+    try:
+        req = Request(server_url.rstrip("/") + "/health/status")
+        with urlopen(req, timeout=3) as resp:  # noqa: S310 — local URL
+            payload = json.loads(resp.read().decode("utf-8", errors="replace"))
+    except Exception:  # noqa: BLE001 — old server or transient error is fine
+        return None, None
+    if not isinstance(payload, dict):
+        return None, None
+    state = payload.get("state") or payload.get("indexing_state") or "unknown"
+    chunk_count = (
+        payload.get("chunk_count")
+        or payload.get("total_chunks")
+        or payload.get("document_count")
+    )
+    parts = [f"indexing={state}"]
+    if isinstance(chunk_count, int):
+        parts.append(f"chunks={chunk_count}")
+    return ", ".join(parts), payload
+
+
 def _check_optional_dep(provider: str, module_name: str, extra: str) -> CheckResult:
     """Report on an optional Python package that a chosen provider needs."""
     if shutil.which("python3"):
@@ -314,7 +404,7 @@ def _check_gitignore(project_root: Path) -> CheckResult:
 
 def run_doctor(server_url_override: str | None = None) -> DoctorReport:
     """Run every check and return a structured report."""
-    project_root = resolve_project_root()
+    project_root, resolved_via = resolve_project_root_with_strategy()
     state_dir = project_root / STATE_DIR_NAME
     runtime_file: Path | None
     if state_dir.exists():
@@ -327,7 +417,8 @@ def run_doctor(server_url_override: str | None = None) -> DoctorReport:
 
     checks: list[CheckResult] = []
     checks.append(_check_python())
-    checks.append(_check_project_init(project_root, state_dir))
+    checks.append(_check_version())
+    checks.append(_check_project_init(project_root, state_dir, resolved_via))
     checks.append(_check_provider_config(state_dir))
     checks.extend(_check_api_keys())
 
@@ -338,6 +429,13 @@ def run_doctor(server_url_override: str | None = None) -> DoctorReport:
         cfg = None
     if cfg and cfg.embedding.provider.lower() == "cohere":
         checks.append(_check_optional_dep("cohere", "cohere", "cohere"))
+
+    # Issue #146 check #8 — surface graphrag's langextract dependency.
+    if cfg and getattr(getattr(cfg, "graphrag", None), "enabled", False):
+        checks.append(
+            _check_optional_dep("graphrag (langextract)", "langextract", "graphrag")
+        )
+
     checks.append(_check_gitignore(project_root))
 
     checks.append(_check_server(server_url, runtime_file))
@@ -352,6 +450,49 @@ def run_doctor(server_url_override: str | None = None) -> DoctorReport:
     )
 
 
+def apply_safe_fixes(report: DoctorReport) -> list[str]:
+    """Apply the subset of fixes that are safe + idempotent + offline.
+
+    Returns the list of human-readable actions taken (empty if nothing to fix).
+    Used by ``agent-brain doctor --fix``. Anything that calls the network,
+    modifies user code, or requires an API key is *not* covered here — the
+    user must still address those manually.
+    """
+    actions: list[str] = []
+    project_root = Path(report.project_root)
+    state_dir = Path(report.state_dir)
+    for check in report.checks:
+        if check.name == "gitignore_state_dir" and check.status != SEVERITY_OK:
+            gi = project_root / ".gitignore"
+            line = f"{STATE_DIR_NAME}/\n"
+            if gi.exists():
+                content = gi.read_text()
+                if not content.endswith("\n"):
+                    content += "\n"
+                gi.write_text(content + line)
+            else:
+                gi.write_text(line)
+            actions.append(f"Added {STATE_DIR_NAME}/ to {gi}.")
+        elif check.name == "project_initialized" and check.status == SEVERITY_FAIL:
+            # Create the state dir + a minimal config.json shell so a follow-up
+            # `agent-brain init` (or any command) has something to read.
+            state_dir.mkdir(parents=True, exist_ok=True)
+            cfg_json = state_dir / "config.json"
+            if not cfg_json.exists():
+                cfg_json.write_text(
+                    json.dumps(
+                        {
+                            "project_root": str(project_root),
+                            "created_by": "agent-brain doctor --fix",
+                        },
+                        indent=2,
+                    )
+                    + "\n"
+                )
+                actions.append(f"Created {cfg_json}.")
+    return actions
+
+
 def doctor_hint_message(project_root: Path | None = None) -> str:
     """Suggest the doctor command — and call out the most likely setup issue.
 

{agent_brain_cli-10.0.3 → agent_brain_cli-10.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "agent-brain-cli"
-version = "10.0.3"
+version = "10.0.5"
 description = "Agent Brain CLI - Command-line interface for managing AI agent memory and knowledge retrieval"
 authors = ["Spillwave Solutions"]
 readme = "README.md"
@@ -27,7 +27,7 @@ httpx = "^0.28.0"
 rich = "^13.9.0"
 pyyaml = "^6.0.0"
 pydantic = "^2.10.0"
-agent-brain-rag = "^10.0.3"
+agent-brain-rag = "^10.0.5"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.0"