blq-cli 0.10.2__tar.gz → 0.11.0__tar.gz

{blq_cli-0.10.2 → blq_cli-0.11.0}/CLAUDE.md

@@ -125,6 +125,19 @@ blq (Python CLI)
     └── Optionally uses duck_hunt extension for 60+ format parsing
 ```
 
+### Service Layer
+
+Shared business logic in `src/blq/services/`, called by both CLI and MCP:
+
+| Module | Functions | Purpose |
+|--------|-----------|---------|
+| `refs.py` | `parse_ref()`, `resolve_run_ref()` | Canonical ref parsing and resolution |
+| `query.py` | `query_status()`, `query_history()`, `query_events()`, `query_diff()` | Database queries |
+| `inspect.py` | `get_source_context()`, `get_log_context()`, `get_git_context()`, `get_fingerprint_history()` | Event context enrichment |
+| `execution.py` | `run_result_to_concise()` | RunResult → concise dict conversion |
+
+Services take `BlqStorage` and return structured data. No argparse or MCP coupling.
+
 ### Storage Modes
 
 BIRD is the default storage mode. Legacy parquet mode is still supported:

{blq_cli-0.10.2 → blq_cli-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blq-cli
-Version: 0.10.2
+Version: 0.11.0
 Summary: Buidl Log Query - capture and query build/test logs with DuckDB
 Project-URL: Homepage, https://blq-cli.readthedocs.com/
 Project-URL: Repository, https://github.com/teaguesterling/blq-cli

blq_cli-0.11.0/docs/superpowers/specs/2026-03-29-unified-service-layer-design.md

@@ -0,0 +1,126 @@
+# Unified Service Layer Design
+
+## Problem
+
+CLI and MCP implement the same operations independently, causing:
+- Query results that can diverge silently between CLI and MCP
+- ~500 lines of duplicated logic across serve.py and commands/
+- Every new feature requires parallel implementation in both layers
+- Two parallel ref parsers for the same syntax
+- MCP shells out to `blq run` as a subprocess instead of sharing the execution path
+
+## Architecture
+
+A new `src/blq/services/` package containing pure business logic functions. Each function takes a `BlqStorage` instance and query parameters, returns structured data (dicts/lists). No argparse, no MCP, no output formatting.
+
+```
+CLI (argparse)  →  services/  ←  MCP (fastmcp)
+                      ↓
+                  BlqStorage
+                      ↓
+                   DuckDB
+```
+
+**The rule:** Services return data. CLI formats it for the terminal. MCP serializes it as JSON. Neither the CLI nor MCP contains query logic.
+
+## Approach
+
+**Bottom-up extraction.** Start with shared query logic (inspect helpers, history, ref resolution), leave execution as subprocess for now. The subprocess gives crash isolation; eliminating it is a follow-up.
+
+**serve.py stays as one file** but gets thinner. After extraction, `_*_impl()` functions become thin adapters calling service functions. Splitting serve.py into `mcp/` modules is a follow-up once the service layer is stable.
+
+## Module Layout
+
+```
+src/blq/services/
+├── __init__.py        # Re-exports for convenience
+├── refs.py            # Canonical ref resolver
+├── query.py           # status, history, events, diff
+├── inspect.py         # Event inspection with context layers
+├── execution.py       # RunResult → concise dict conversion
+└── commands.py        # list/register/unregister operations
+```
+
+## Service Function Signatures
+
+All services take `BlqStorage` as first argument (caller opens and passes it):
+
+```python
+# refs.py
+def parse_ref(ref: str) -> ParsedRef
+def resolve_run(storage: BlqStorage, ref: str) -> dict | None
+
+# query.py
+def query_status(storage: BlqStorage) -> list[dict]
+def query_history(storage: BlqStorage, limit: int, source: str | None, status: str | None) -> list[dict]
+def query_events(storage: BlqStorage, severity: str | None, run_id: int | None,
+                  source: str | None, file_pattern: str | None, limit: int) -> dict
+def query_diff(storage: BlqStorage, run1: int, run2: int) -> dict
+
+# inspect.py
+def inspect_event(storage: BlqStorage, ref: str, source_root: Path,
+                   include_source: bool, include_git: bool, include_fingerprint: bool) -> dict
+
+# execution.py
+def run_result_to_concise(result: dict, source_name: str) -> dict
+
+# commands.py
+def list_commands(config: BlqConfig) -> list[dict]
+def register_command(config: BlqConfig, name: str, cmd: str, **kwargs) -> dict
+def unregister_command(config: BlqConfig, name: str) -> dict
+```
+
+## What Gets Extracted
+
+### refs.py — Canonical ref resolver
+Merges `resolve_ref()` from `management.py:35` and `_parse_ref()` + `_parse_run_ref()` from `serve.py:227/262`. Two parallel parsers for the same `tag:serial:event` syntax become one.
+
+### query.py — Status, history, events, diff
+- **status**: Merges `cmd_status()` (management.py) and `_status_impl()` (serve.py). Shared: `status_str` computation, `run_ref` construction.
+- **history**: Merges `cmd_history()` and `_history_impl()`. SQL query and status mapping are near-identical.
+- **events**: Merges `cmd_events()` and `_errors_impl()`/`_warnings_impl()`/`_events_impl()`. WHERE building, suppression logic, event-dict shaping.
+- **diff**: Currently MCP-only. Service function makes it available to CLI too.
+
+### inspect.py — Event inspection with context
+Moves four private helpers from `events.py` into shared functions: `_get_log_context()`, `_get_source_context()`, `_get_git_context()`, `_get_fingerprint_history()`. Eliminates ~180 lines of duplication in serve.py.
+
+### execution.py — Result conversion
+Extracts the `RunResult → concise dict` shaping from `_run_impl()` and `_exec_impl()` in serve.py (~100 lines duplicated between the two). Subprocess bridge stays; only the response shaping is shared.
+
+### commands.py — Command registry
+Extracts command list/register/unregister logic that's currently in both `registry.py` and serve.py's `_register_command_impl()`.
+
+## Migration Strategy
+
+**Phase 1: Extract services (no callers changed)**
+- Create `services/` modules with shared logic
+- Write tests for each service function independently
+- Existing CLI and MCP untouched
+
+**Phase 2: Wire CLI to services**
+- CLI handlers call service functions, keep only argparse + formatting
+- Run full test suite after each command migration
+
+**Phase 3: Wire MCP to services**
+- MCP `_*_impl()` functions call service functions
+- Subprocess bridge for run/exec stays
+- serve.py shrinks from ~4,400 to ~2,000 lines
+
+**Phase 4: Cleanup**
+- Remove dead code
+- Verify CLI and MCP produce identical results
+
+## What This Does NOT Do
+
+- **No direct execution from MCP** — subprocess bridge stays (crash isolation)
+- **No serve.py split** — stays as one file, just thinner
+- **No new features** — pure refactor, behavior unchanged
+- **No storage layer changes** — BlqStorage stays as-is
+
+## Success Criteria
+
+- All existing tests pass with no changes
+- CLI and MCP produce identical results for: status, history, events, info, inspect, diff
+- serve.py shrinks by ~1,500 lines
+- No query logic remains in CLI command handlers or MCP `_*_impl()` functions
+- One canonical ref resolver used everywhere

{blq_cli-0.10.2 → blq_cli-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "blq-cli"
-version = "0.10.2"
+version = "0.11.0"
 description = "Buidl Log Query - capture and query build/test logs with DuckDB"
 readme = "README.md"
 license = "MIT"

blq_cli-0.11.0/src/blq/services/__init__.py

@@ -0,0 +1,32 @@
+"""Shared service layer for blq.
+
+Services contain pure business logic called by both CLI and MCP.
+Each function takes a BlqStorage instance and returns structured data.
+No argparse, no MCP, no output formatting.
+"""
+from __future__ import annotations
+
+from blq.services.execution import run_result_to_concise
+from blq.services.inspect import (
+    get_fingerprint_history,
+    get_git_context,
+    get_log_context,
+    get_source_context,
+)
+from blq.services.query import query_diff, query_events, query_history, query_status
+from blq.services.refs import ParsedRef, parse_ref, resolve_run_ref
+
+__all__ = [
+    "ParsedRef",
+    "parse_ref",
+    "resolve_run_ref",
+    "query_status",
+    "query_history",
+    "query_events",
+    "query_diff",
+    "get_source_context",
+    "get_log_context",
+    "get_git_context",
+    "get_fingerprint_history",
+    "run_result_to_concise",
+]

blq_cli-0.11.0/src/blq/services/execution.py

@@ -0,0 +1,74 @@
+"""Execution services for blq.
+
+Provides shared business logic for shaping RunResult JSON into the concise
+format returned to MCP callers and CLI consumers.
+No argparse, no MCP, no output formatting.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def run_result_to_concise(full_result: dict[str, Any], source_name: str) -> dict[str, Any]:
+    """Convert a full RunResult JSON dict into the concise MCP response format.
+
+    The ``full_result`` is the dict produced by ``RunResult.to_json()`` (already
+    parsed from JSON).  ``source_name`` is used to build ``run_ref`` when the
+    result does not contain one (e.g. the caller knows the registered command
+    name but the result only has a numeric run_id).
+
+    Always-present keys in the returned dict:
+        run_ref       – "<source_name>:<run_id>" or None when run_id is absent
+        cmd           – the command string from full_result["command"]
+        status        – from full_result or derived from exit_code
+        exit_code     – int
+        duration_sec  – float rounded to 1 decimal place
+        summary       – dict from full_result
+        output_stats  – {"lines": int, "bytes": int}
+
+    Conditionally-present keys (only when the value is non-empty/non-None):
+        status_reason – str
+        errors        – first 10 items
+        warnings      – first 5 items
+        infos         – first 5 items
+    """
+    run_id = full_result.get("run_id")
+    exit_code = full_result.get("exit_code", 0)
+    status = full_result.get("status", "FAIL" if exit_code != 0 else "OK")
+    output_stats_raw = full_result.get("output_stats", {})
+
+    concise: dict[str, Any] = {
+        "run_ref": f"{source_name}:{run_id}" if run_id is not None else None,
+        "cmd": full_result.get("command"),
+        "status": status,
+        "exit_code": exit_code,
+        "duration_sec": round(full_result.get("duration_sec", 0), 1),
+        "summary": full_result.get("summary", {}),
+        "output_stats": {
+            "lines": output_stats_raw.get("lines", 0),
+            "bytes": output_stats_raw.get("bytes", 0),
+        },
+    }
+
+    # Include status_reason when present and non-None
+    status_reason = full_result.get("status_reason")
+    if status_reason:
+        concise["status_reason"] = status_reason
+
+    # Include errors (capped at 10, summary has total count)
+    errors = full_result.get("errors", [])
+    if errors:
+        concise["errors"] = errors[:10]
+
+    # Include warnings (top 5)
+    warnings = full_result.get("warnings", [])
+    if warnings:
+        concise["warnings"] = warnings[:5]
+
+    # Include info/summary events (top 5)
+    infos = full_result.get("infos", [])
+    if infos:
+        concise["infos"] = infos[:5]
+
+    return concise

blq_cli-0.11.0/src/blq/services/inspect.py

@@ -0,0 +1,224 @@
+"""Inspect service: context-fetching functions for event enrichment.
+
+Provides source, log, git, and fingerprint context for events.
+Used by both CLI (commands/events.py) and MCP (serve.py).
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from blq.storage import BlqStorage
+
+logger = logging.getLogger(__name__)
+
+
+def get_source_context(
+    ref_file: str | None,
+    ref_line: int | None,
+    source_root: Path,
+    context_lines: int = 3,
+) -> str | None:
+    """Get source file context around a specific line.
+
+    Args:
+        ref_file: Path to the source file (relative to source_root).
+        ref_line: 1-indexed line number of the event.
+        source_root: Root path for resolving relative file paths.
+        context_lines: Number of lines before/after to include.
+
+    Returns:
+        Formatted context string with line numbers and markers, or None.
+    """
+    if ref_file is None or ref_line is None:
+        return None
+
+    try:
+        import blq.output as output_mod
+
+        return output_mod.read_source_context(
+            ref_file,
+            ref_line,
+            ref_root=str(source_root),
+            context=context_lines,
+        )
+    except Exception:
+        logger.debug("Failed to get source context for %s:%s", ref_file, ref_line, exc_info=True)
+        return None
+
+
+def get_log_context(
+    storage: BlqStorage | None,
+    run_id: int,
+    log_line_start: int | None,
+    log_line_end: int | None,
+    context_lines: int = 3,
+) -> str | None:
+    """Get log output context around the event's line range.
+
+    Args:
+        storage: BlqStorage instance with get_output().
+        run_id: The run ID to fetch output for.
+        log_line_start: 1-indexed start line of the event in the log.
+        log_line_end: 1-indexed end line of the event in the log.
+        context_lines: Number of lines before/after to include.
+
+    Returns:
+        Formatted context string, or None.
+    """
+    if log_line_start is None or log_line_end is None:
+        return None
+
+    if storage is None:
+        return None
+
+    try:
+        import blq.output as output_mod
+
+        output_bytes = storage.get_output(run_id)
+        if output_bytes is None:
+            return None
+
+        content = output_bytes.decode("utf-8", errors="replace")
+        lines = content.splitlines()
+        return output_mod.format_context(
+            lines,
+            log_line_start,
+            log_line_end,
+            context=context_lines,
+        )
+    except Exception:
+        logger.debug("Failed to get log context for run %s", run_id, exc_info=True)
+        return None
+
+
+def get_git_context(
+    ref_file: str | None,
+    ref_line: int | None,
+    source_root: Path,
+    history_limit: int = 2,
+) -> dict[str, Any] | None:
+    """Get git blame and history context for a source file location.
+
+    Args:
+        ref_file: Path to the source file (relative to source_root).
+        ref_line: Line number for blame info (optional).
+        source_root: Root path for resolving relative file paths.
+        history_limit: Maximum number of recent commits to include.
+
+    Returns:
+        Dict with file, line, blame, and recent_commits, or None.
+    """
+    if ref_file is None:
+        return None
+
+    try:
+        import blq.git as git_mod
+
+        file_path = source_root / ref_file
+        if not file_path.exists():
+            return None
+
+        ctx = git_mod.get_file_context(str(file_path), line=ref_line, history_limit=history_limit)
+
+        result: dict[str, Any] = {
+            "file": ref_file,
+            "line": ref_line,
+        }
+
+        if ctx.last_author:
+            result["blame"] = {
+                "author": ctx.last_author,
+                "commit": ctx.last_commit,
+                "modified": ctx.last_modified.isoformat() if ctx.last_modified else None,
+            }
+
+        if ctx.recent_commits:
+            result["recent_commits"] = [
+                {
+                    "hash": c.short_hash,
+                    "author": c.author,
+                    "time": c.time.isoformat() if c.time else None,
+                    "message": c.message,
+                }
+                for c in ctx.recent_commits
+            ]
+
+        return result
+    except Exception:
+        logger.debug("Failed to get git context for %s", ref_file, exc_info=True)
+        return None
+
+
+def get_fingerprint_history(
+    storage: BlqStorage | None,
+    fingerprint: str | None,
+) -> dict[str, Any] | None:
+    """Get occurrence history for an event fingerprint.
+
+    Queries all events with the same fingerprint and returns summary info
+    including first/last seen and regression detection.
+
+    Args:
+        storage: BlqStorage instance with sql() method.
+        fingerprint: The fingerprint value to look up.
+
+    Returns:
+        Dict with fingerprint, first_seen, last_seen, occurrences,
+        and is_regression, or None.
+    """
+    if fingerprint is None:
+        return None
+
+    if storage is None:
+        return None
+
+    try:
+        result = storage.sql(
+            """
+            SELECT
+                run_serial,
+                run_ref,
+                timestamp,
+                tag
+            FROM blq_load_events()
+            WHERE fingerprint = ?
+            ORDER BY started_at ASC
+            """,
+            [fingerprint],
+        ).fetchall()
+
+        if not result:
+            return None
+
+        first = result[0]
+        last = result[-1]
+
+        # Detect regression: gap > 1 in consecutive run_serial values
+        is_regression = False
+        if len(result) >= 2:
+            run_serials = [r[0] for r in result]
+            for i in range(1, len(run_serials)):
+                if run_serials[i] - run_serials[i - 1] > 1:
+                    is_regression = True
+                    break
+
+        return {
+            "fingerprint": fingerprint[:16] + "..." if len(fingerprint) > 16 else fingerprint,
+            "first_seen": {
+                "run_ref": first[1],
+                "timestamp": first[2].isoformat() if first[2] else None,
+            },
+            "last_seen": {
+                "run_ref": last[1],
+                "timestamp": last[2].isoformat() if last[2] else None,
+            },
+            "occurrences": len(result),
+            "is_regression": is_regression,
+        }
+    except Exception:
+        logger.debug("Failed to get fingerprint history for %s", fingerprint, exc_info=True)
+        return None