crackerjack 0.76.0__tar.gz → 0.76.2__tar.gz

{crackerjack-0.76.0 → crackerjack-0.76.2}/CHANGELOG.md

@@ -1,5 +1,35 @@
 ______________________________________________________________________
 
+## [0.76.2] - 2026-08-28
+
+### Added
+
+- crackerjack: Adopt BodaiCLIBase + real doctor/health (Phase 3 Task 4.5)
+- crackerjack: Bodai.apps entry-point (Phase 5.1)
+
+### Fixed
+
+- ty: Suppress unresolved-import for fallback toml import
+- Update Claude Code MCP docs URL to current canonical location
+
+### Documentation
+
+- readme: Bump Python badge from 3.13+ to 3.14+
+
+### Testing
+
+- guard: Assert all Bodai repos use hatchling build backend
+
+### Internal
+
+- deps: Bump oneiric floor to >=0.19.1
+
+## [0.76.1] - 2026-08-25
+
+### Fixed
+
+- crackerjack: Scope refurb to inner package dir, not repo root
+
 ## [0.75.8] - 2026-08-25
 
 ### Changed

{crackerjack-0.76.0 → crackerjack-0.76.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: crackerjack
-Version: 0.76.0
+Version: 0.76.2
 Summary: Crackerjack Python project management tool
 Project-URL: documentation, https://github.com/lesleslie/crackerjack
 Project-URL: homepage, https://github.com/lesleslie/crackerjack
@@ -39,7 +39,7 @@ Requires-Dist: mcp-common>=0.18.0
 Requires-Dist: mdformat-ruff>=0.1.3
 Requires-Dist: mdformat>=1.0.0
 Requires-Dist: numpy>=2.5.0
-Requires-Dist: oneiric>=0.16.0
+Requires-Dist: oneiric>=0.19.1
 Requires-Dist: pip-audit>=2.10.1
 Requires-Dist: pydantic>=2.13.4
 Requires-Dist: pyleak>=0.2.0
@@ -88,7 +88,7 @@ Description-Content-Type: text/markdown
 [![Runtime: oneiric](https://img.shields.io/badge/runtime-oneiric-6e5494)](https://github.com/lesleslie/oneiric)
 [![Framework: FastMCP](https://img.shields.io/badge/framework-FastMCP-0ea5e9)](https://github.com/jlowin/fastmcp)
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
-[![Python: 3.13+](https://img.shields.io/badge/python-3.13%2B-green)](https://www.python.org/downloads/)
+[![Python: 3.14+](https://img.shields.io/badge/python-3.14%2B-green)](https://www.python.org/downloads/)
 
 ## Bodai Ecosystem Role
 

{crackerjack-0.76.0 → crackerjack-0.76.2}/README.md

@@ -4,7 +4,7 @@
 [![Runtime: oneiric](https://img.shields.io/badge/runtime-oneiric-6e5494)](https://github.com/lesleslie/oneiric)
 [![Framework: FastMCP](https://img.shields.io/badge/framework-FastMCP-0ea5e9)](https://github.com/jlowin/fastmcp)
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
-[![Python: 3.13+](https://img.shields.io/badge/python-3.13%2B-green)](https://www.python.org/downloads/)
+[![Python: 3.14+](https://img.shields.io/badge/python-3.14%2B-green)](https://www.python.org/downloads/)
 
 ## Bodai Ecosystem Role
 

{crackerjack-0.76.0 → crackerjack-0.76.2}/crackerjack/__main__.py

@@ -41,7 +41,6 @@ def crackerjack_diag() -> None:
 
 
 atexit.register(crackerjack_diag)
-from mcp_common.cli import MCPServerCLIFactory
 from rich.console import Console
 
 logger = logging.getLogger(__name__)
@@ -52,6 +51,7 @@ from crackerjack.cli import (
     BumpOption,
     create_options,
 )
+from crackerjack.cli.base import CrackerjackCLI
 from crackerjack.cli.cache_handlers import _handle_cache_commands
 from crackerjack.cli.handlers import check_docs, handle_config_updates, validate_docs
 from crackerjack.cli.handlers.advanced import handle_advanced_optimizer
@@ -86,24 +86,19 @@ from crackerjack.cli.semantic_handlers import (
     handle_semantic_stats,
 )
 from crackerjack.config import CrackerjackSettings, load_settings
-from crackerjack.config.mcp_settings_adapter import CrackerjackMCPSettings
 
 if t.TYPE_CHECKING:
     from crackerjack.cli.options import Options
 
-mcp_settings = CrackerjackMCPSettings.load_for_crackerjack()
+# MCPServerCLIFactory was replaced by CrackerjackCLI (oneiric 0.19
+# BodaiCLIBase). mcp_settings is no longer needed at module level.
 
-factory = MCPServerCLIFactory(
-    server_name="crackerjack",
-    settings=mcp_settings,
+app = CrackerjackCLI(
     start_handler=start_handler,
     stop_handler=stop_handler,
     health_probe_handler=health_probe_handler,
 )
 
-app = factory.create_app()
-app.info.help = "Crackerjack MCP Server CLI"
-
 console = Console()
 
 
@@ -135,13 +130,9 @@ _safe_add_typer(app, "crackerjack.cli.skills_cli", "app", "skills")
 _safe_add_typer(app, "crackerjack.cli.coverage_ratchet_cli", "app", "coverage-ratchet")
 
 
-@app.callback(invoke_without_command=True)
-def version_option(
-    version: bool = typer.Option(False, "--version", help="Show version and exit"),
-) -> None:
-    if version:
-        console.print(f"[cyan]Crackerjack[/cyan] [dim]v{__version__}[/dim]")
-        raise typer.Exit(0)
+# --version / version subcommand are wired by BodaiCLIBase; the previous
+# @app.callback(invoke_without_command=True) version_option is removed
+# to avoid a duplicate-callback Typer crash.
 
 
 def _detect_package_name_standalone() -> str:
@@ -771,45 +762,37 @@ def run_tests(
     raise typer.Exit(result.returncode)
 
 
-@app.command("health")
+# `crackerjack health` is provided by BodaiCLIBase via CrackerjackCLI; it
+# dispatches to CrackerjackCLI._health_probe() (real probe, not stub). The
+# previous rich-formatted `health_command` is preserved as a regular helper
+# for callers that need component-scoped health checks; see
+# ``crackerjack.cli.handlers.health.handle_health_check`` for the underlying
+# logic.
 def health_command(
-    component: str | None = typer.Option(
-        None,
-        "--component",
-        "-c",
-        help="Specific component to check (adapters, managers, services, all)",
-    ),
-    json_output: bool = typer.Option(
-        False,
-        "--json",
-        help="Output results as JSON",
-    ),
-    verbose: bool = typer.Option(
-        False,
-        "--verbose",
-        "-v",
-        help="Show detailed health information",
-    ),
-    quiet: bool = typer.Option(
-        False,
-        "--quiet",
-        "-q",
-        help="Only show exit code (no output)",
-    ),
-) -> t.Never:
+    component: str | None = None,
+    json_output: bool = False,
+    verbose: bool = False,
+    quiet: bool = False,
+    pkg_path: Path | None = None,
+) -> int:
+    """Component-scoped health check helper.
+
+    Returns the exit code from :func:`handle_health_check`. Kept for
+    tests/test___main__.py which imports ``health_command`` directly.
+    """
     from pathlib import Path
 
     from crackerjack.cli.handlers.health import handle_health_check
 
-    pkg_path = Path.cwd()
-    exit_code = handle_health_check(
+    if pkg_path is None:
+        pkg_path = Path.cwd()
+    return handle_health_check(
         component=component,
         json_output=json_output,
         verbose=verbose,
         quiet=quiet,
         pkg_path=pkg_path,
     )
-    raise typer.Exit(exit_code)
 
 
 @app.command()

crackerjack-0.76.2/crackerjack/cli/__init__.py

@@ -0,0 +1,34 @@
+from .coverage_ratchet_cli import app as coverage_ratchet_app
+from .handlers import (
+    handle_interactive_mode,
+    handle_standard_mode,
+)
+from .options import CLI_OPTIONS, BumpOption, Options, create_options
+from .version import get_package_version
+
+__all__ = [
+    "CLI_OPTIONS",
+    "BumpOption",
+    "Options",
+    "coverage_ratchet_app",
+    "create_options",
+    "get_package_version",
+    "handle_interactive_mode",
+    "handle_standard_mode",
+]
+
+
+def __getattr__(name: str):
+    """Lazily expose the umbrella Typer app.
+
+    Phase 5.1: the Bodai ecosystem discovers CLI apps via the
+    ``bodai.apps`` entry-point group. The canonical ``app`` object lives in
+    ``crackerjack.__main__`` (where the legacy ``[project.scripts]`` runner
+    picks it up). Lazy-importing here avoids a hard
+    ``crackerjack.cli <-> crackerjack.__main__`` cycle at module-import time.
+    """
+    if name == "app":
+        from crackerjack.__main__ import app as _umbrella_app
+
+        return _umbrella_app
+    raise AttributeError(name)

crackerjack-0.76.2/crackerjack/cli/base.py

@@ -0,0 +1,163 @@
+"""CrackerjackCLI — BodaiCLIBase subclass for the crackerjack CLI entrypoint.
+
+Adopts oneiric 0.19.0's :class:`oneiric.cli.base.BodaiCLIBase` as the
+foundation for the crackerjack CLI. Adds REAL ``_doctor_checks()`` and
+``_health_probe()`` implementations that call into crackerjack's existing
+health surface (``crackerjack.cli.handlers.health``) — not stub returns.
+
+This file deliberately avoids ``logging.Logger.exception(component=...)`` —
+``ty`` strict type checker rejects the kwarg. We use ``extra={"component":
+self.component_name}`` per project CLAUDE.md guidance.
+"""
+
+from __future__ import annotations
+
+import logging
+import typing as t
+from pathlib import Path
+from typing import Any
+
+from mcp_common.cli import MCPServerCLIFactory
+from oneiric.cli.base import BodaiCLIBase
+
+logger = logging.getLogger(__name__)
+
+
+class CrackerjackCLI(BodaiCLIBase):
+    """BodaiCLIBase subclass for the crackerjack CLI.
+
+    Wires in version/doctor/health global commands from :class:`BodaiCLIBase`
+    and the legacy MCP server lifecycle commands (start/stop/restart/status)
+    from :class:`MCPServerCLIFactory`. Doctor and health checks are real — they
+    delegate to ``crackerjack.cli.handlers.health`` instead of stubbing.
+    """
+
+    def __init__(
+        self,
+        *,
+        start_handler: t.Callable[[], None] | None = None,
+        stop_handler: t.Callable[..., None] | None = None,
+        health_probe_handler: t.Callable[[], Any] | None = None,
+        help: str | None = "Crackerjack MCP Server CLI",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(component_name="crackerjack", help=help, **kwargs)
+        self._register_lifecycle_commands(
+            start_handler=start_handler,
+            stop_handler=stop_handler,
+            health_probe_handler=health_probe_handler,
+        )
+
+    # ------------------------------------------------------------------
+    # Lifecycle commands (start/stop/restart/status) inherited from
+    # MCPServerCLIFactory. We compose rather than copy the factory so
+    # upstream bug fixes flow through automatically.
+    # ------------------------------------------------------------------
+    def _register_lifecycle_commands(
+        self,
+        *,
+        start_handler: t.Callable[[], None] | None,
+        stop_handler: t.Callable[..., None] | None,
+        health_probe_handler: t.Callable[[], Any] | None,
+    ) -> None:
+        factory = MCPServerCLIFactory(
+            server_name="crackerjack",
+            start_handler=start_handler,
+            stop_handler=stop_handler,
+            health_probe_handler=health_probe_handler,
+        )
+        lifecycle_app = factory.create_app()
+
+        # BodaiCLIBase already provides `health` (calls our _health_probe
+        # override). Drop the factory's `health` command to avoid the
+        # Typer duplicate-command error.
+        for typer_info in getattr(lifecycle_app, "registered_commands", []):
+            # Skip the factory's "health" command so BodaiCLIBase's is canonical.
+            if getattr(typer_info, "name", None) == "health":
+                continue
+            self.registered_commands.append(typer_info)
+
+        for typer_info in getattr(lifecycle_app, "registered_groups", []):
+            self.registered_groups.append(typer_info)
+
+    # ------------------------------------------------------------------
+    # BodaiCLIBase subclass hooks — REAL checks, not stubs.
+    # ------------------------------------------------------------------
+    def _doctor_checks(self) -> dict[str, Any]:
+        """Run doctor checks via the existing crackerjack health handlers.
+
+        Returns a non-empty dict with one entry per category
+        (adapters/managers/services). Each entry contains a ``status`` and
+        ``detail`` field that the global ``doctor`` command renders.
+        """
+        from crackerjack.cli.handlers.health import (
+            _check_adapters,
+            _check_managers,
+            _check_services,
+        )
+
+        pkg_path = Path.cwd()
+        checks: dict[str, Any] = {}
+
+        for label, fn in (
+            ("adapters", _check_adapters),
+            ("managers", _check_managers),
+            ("services", _check_services),
+        ):
+            try:
+                health = fn(pkg_path)
+            except Exception as exc:
+                logger.exception(
+                    "doctor-category-failed",
+                    extra={"component": self.component_name, "category": label},
+                )
+                checks[label] = {
+                    "status": "unhealthy",
+                    "detail": f"{type(exc).__name__}: {exc}",
+                }
+                continue
+            checks[label] = {
+                "status": str(health.overall_status.value),
+                "detail": (
+                    f"total={health.total} healthy={health.healthy} "
+                    f"degraded={health.degraded} unhealthy={health.unhealthy}"
+                ),
+                "total": health.total,
+                "healthy": health.healthy,
+                "degraded": health.degraded,
+                "unhealthy": health.unhealthy,
+            }
+        return checks
+
+    def _health_probe(self) -> dict[str, Any]:
+        """Probe crackerjack runtime health via the existing handler.
+
+        Returns a real snapshot (not the UNAVAILABLE-stub from
+        :class:`BodaiCLIBase`). The ``status`` field reflects whether the
+        underlying handle_health_check returned a zero exit code.
+        """
+        from crackerjack.cli.handlers.health import handle_health_check
+
+        pkg_path = Path.cwd()
+        try:
+            exit_code = handle_health_check(pkg_path=pkg_path, quiet=True)
+        except Exception as exc:
+            logger.exception(
+                "health-probe-failed",
+                extra={"component": self.component_name},
+            )
+            return {
+                "status": "unhealthy",
+                "component": self.component_name,
+                "version": self.component_version,
+                "error": f"{type(exc).__name__}: {exc}",
+            }
+        return {
+            "status": "healthy" if exit_code == 0 else "degraded",
+            "exit_code": exit_code,
+            "component": self.component_name,
+            "version": self.component_version,
+        }
+
+
+__all__ = ["CrackerjackCLI"]

{crackerjack-0.76.0 → crackerjack-0.76.2}/crackerjack/core/preflight.py

@@ -98,6 +98,11 @@ class PreflightFixer:
         # fallback when no HookSettings are provided — that field is on the
         # way out but kept read-compatible during the rollout.
         self._settings: HookSettings = settings or HookSettings()
+        # Resolve the inner package directory (e.g. ``fastblocks/``) once so
+        # tool commands like refurb can target it instead of ``.`` — the
+        # latter scans the whole repo, including ``.venv``, which produces
+        # spurious diagnostics against installed third-party wheels.
+        self._package_dir: Path | None = None
 
     async def run(self, run_id: str, iteration: int) -> PreflightReport:
         tools = self._enabled_tools()
@@ -250,9 +255,74 @@ class PreflightFixer:
             selects = ",".join(self._config.ruff_select_extra)
             return ["uv", "run", "ruff", "check", "--select", selects, "--fix", "."]
         if tool == "refurb":
-            return ["uv", "run", "refurb", "."]
+            # Refurb walks the path it is given. ``.`` would scan the whole
+            # project — including ``.venv``, where installed third-party
+            # wheels live and produce diagnostics that have nothing to do
+            # with this repo's source. Target the discovered package
+            # directory instead, falling back to the repo root when no
+            # subdirectory can be identified (matches the legacy behaviour).
+            target = self._resolve_package_target()
+            return ["uv", "run", "refurb", str(target)]
         return []
 
+    def _resolve_package_target(self) -> Path:
+        """Return the inner package directory for refurb-style tool invocations.
+
+        Discovery order:
+          1. ``[tool.hatch.build.targets.wheel] packages = [...]`` from the
+             project's ``pyproject.toml`` (most accurate for hatchling
+             projects where project name and package directory differ).
+          2. ``<project_root>/<project_name>`` (works when they match,
+             e.g. ``fastblocks/``).
+          3. ``<project_root>`` (legacy fallback — scans the whole repo).
+        """
+        if self._package_dir is None:
+            self._package_dir = self._discover_package_dir()
+        return self._package_dir
+
+    def _discover_package_dir(self) -> Path:
+        import tomllib
+
+        root = self._pkg_path
+        pyproject = root / "pyproject.toml"
+        with suppress(Exception):
+            with pyproject.open("rb") as fh:
+                data = tomllib.load(fh)
+            # Hatchling writes under ``[tool.hatchling.build]`` (e.g.
+            # mcp-common) and ``[tool.hatch.build]`` (e.g. crackerjack,
+            # mahavishnu) — check both. ``packages = [...]`` is the
+            # canonical wheel target; ``include = [...]`` is the legacy
+            # synonym crackerjack itself uses.
+            for ns in ("hatch", "hatchling"):
+                wheel_cfg = (
+                    data.get("tool", {})
+                    .get(ns, {})
+                    .get("build", {})
+                    .get("targets", {})
+                    .get("wheel", {})
+                )
+                for key in ("packages", "include"):
+                    listed = wheel_cfg.get(key)
+                    if not isinstance(listed, list) or not listed:
+                        continue
+                    for entry in listed:
+                        if not isinstance(entry, str):
+                            continue
+                        # Hatch glob patterns like ``crackerjack/**/*.py``
+                        # reduce to the package directory itself.
+                        pkg_name = entry.split("/", 1)[0] if "/" in entry else entry
+                        if not pkg_name or "*" in pkg_name:
+                            continue
+                        candidate = root / pkg_name
+                        if candidate.is_dir():
+                            return candidate
+            project_name = data.get("project", {}).get("name")
+            if isinstance(project_name, str) and project_name:
+                candidate = root / project_name
+                if candidate.is_dir():
+                    return candidate
+        return root
+
     def _guard_ruff_fix_invocation(
         self,
         tool: str,

{crackerjack-0.76.0 → crackerjack-0.76.2}/crackerjack/services/config_parsers.py

@@ -104,7 +104,7 @@ class TOMLParser:
             return tomli_w.dumps(config)
 
         try:
-            import toml
+            import toml  # ty: ignore[unresolved-import]
 
             return t.cast(str, toml.dumps(config))
         except ImportError:

{crackerjack-0.76.0 → crackerjack-0.76.2}/docs/MCP_SERVER_AUDIT.md

@@ -520,11 +520,10 @@ ______________________________________________________________________
 
 - [MCP Specification](https://modelcontextprotocol.io/) - Official protocol docs
 - [FastMCP](https://github.com/jlowin/fastmcp) - Python MCP server framework
-- [Claude Code MCP Docs](https://docs.anthropic.com/claude-code/mcp) - Official Claude Code integration
+- [Claude Code MCP Docs](https://code.claude.com/docs/en/mcp) - Official Claude Code integration
 
 ### Community
 
-- [r/MCP subreddit](../.cache/crackerjack/uv/archive-v0/ctwDt0rtppTBnmtDq5Hrz/bin/mcp) - MCP discussions & tools
 - [MCP Discord](https://discord.gg/mcp) - Real-time chat (if exists)
 
 ______________________________________________________________________

{crackerjack-0.76.0 → crackerjack-0.76.2}/docs/schemas/document-frontmatter-v1.md

@@ -138,7 +138,7 @@ Two open questions were resolved before migration began. Both are binding for Ph
 
 - [`docs/schemas/topic-vocabulary-v1.md`](./topic-vocabulary-v1.md) — controlled topic list (seed + amendment rule).
 - [`docs/plans/PLAN_INDEX.md`](../plans/PLAN_INDEX.md) — the index regenerated from frontmatter in Phase P6.
-- [`.claude/decisions/README.md`](../../.claude/decisions/README.md) — the decision index; Status column re-derived from per-decision frontmatter in Phase P5.
+- `.claude/decisions/README.md` — the decision index (gitignored; refer to local repo for content); Status column re-derived from per-decision frontmatter in Phase P5.
 
 ## Change History
 

{crackerjack-0.76.0 → crackerjack-0.76.2}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "crackerjack"
-version = "0.76.0"
+version = "0.76.2"
 description = "Crackerjack Python project management tool"
 readme = "README.md"
 authors = [
@@ -45,7 +45,7 @@ dependencies = [
     "mdformat>=1.0.0",
     "mdformat-ruff>=0.1.3",
     "numpy>=2.5.0",
-    "oneiric>=0.16.0",
+    "oneiric>=0.19.1",
     "pip-audit>=2.10.1",
     "pyleak>=0.2.0",
     "pyscn==1.5.0",
@@ -95,6 +95,11 @@ text = "BSD-3-CLAUSE"
 [project.scripts]
 crackerjack = "crackerjack.__main__:cli"
 
+# Bodai umbrella entry-point (Phase 5.1). Discovered by the bodai CLI
+# dispatcher via importlib.metadata under the "bodai.apps" group.
+[project.entry-points."bodai.apps"]
+crackerjack = "crackerjack.cli:app"
+
 [project.urls]
 documentation = "https://github.com/lesleslie/crackerjack"
 homepage = "https://github.com/lesleslie/crackerjack"