techtree 0.1.0__py3-none-any.whl

techtree/cli/commands/doctor.py

@@ -0,0 +1,147 @@
+"""``techtree doctor``. Spec section 12.5.
+
+The command decides nothing. It asks the Doctor service what it found, turns
+warnings into messages, turns blocking failures into a typed prerequisite
+error, and hands the whole thing to the envelope machinery. Whether a check
+blocks, and which repairs are worth offering, are the service's calls.
+
+A blocking failure is reported as a failure — non-zero exit, ``ok`` false — and
+the report still travels in ``data``. A caller that asked what is wrong with
+its machine should get the answer along with the verdict, not instead of it.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from techtree.cli.commands.climb import build_catalog_service
+from techtree.cli.context import CliContext, cli_context
+from techtree.cli.invoke import CommandResult, invoke_command
+from techtree.doctor.service import DoctorReport, DoctorService
+from techtree.errors import PrerequisiteError
+from techtree.models.campaign import CampaignSpec
+from techtree.models.cli import CheckStatus, CliMessage, DoctorCheck, MessageLevel
+
+__all__ = ["doctor_command", "render_doctor_report"]
+
+COMMAND = "doctor"
+
+#: How each status is coloured for a person. Ignored entirely when colour is
+#: off or stdout is not a terminal.
+_STATUS_STYLE: dict[CheckStatus, str] = {
+    CheckStatus.PASS: "green",
+    CheckStatus.WARN: "yellow",
+    CheckStatus.FAIL: "red",
+    CheckStatus.SKIP: "dim",
+}
+
+
+def doctor_command(
+    ctx: typer.Context,
+    for_evaluation: bool = typer.Option(
+        False,
+        "--for-evaluation",
+        help=(
+            "Also check what running a Climb for real needs, and treat anything "
+            "missing as a reason to stop rather than a note."
+        ),
+    ),
+    climb: str | None = typer.Option(
+        None,
+        "--climb",
+        metavar="REFERENCE",
+        help=(
+            "Check the subject a particular Climb would run: its model "
+            "credential and its container image. Implies --for-evaluation."
+        ),
+    ),
+) -> None:
+    """Run DoctorService and emit checks plus repair actions."""
+    context = cli_context(ctx)
+
+    def action() -> CommandResult[DoctorReport]:
+        service = DoctorService(context.paths, context.settings)
+        checks = service.run(
+            for_evaluation=for_evaluation or climb is not None,
+            campaign=_campaign_for(context, climb),
+        )
+        blocking = service.blocking_failures(checks)
+
+        return CommandResult(
+            data=service.report(checks),
+            messages=[
+                CliMessage(
+                    level=MessageLevel.INFO,
+                    code="doctor_summary",
+                    text=_summary(len(checks), len(blocking)),
+                )
+            ],
+            warnings=[
+                CliMessage(level=MessageLevel.WARNING, code=check.id, text=check.detail)
+                for check in service.warnings(checks)
+            ],
+            next_actions=service.next_actions(checks),
+            error=_blocking_error(blocking) if blocking else None,
+        )
+
+    invoke_command(context, COMMAND, action, render_data=_render)
+
+
+def _campaign_for(context: CliContext, reference: str | None) -> CampaignSpec | None:
+    """Resolve the Campaign a named Climb would execute, if one was named.
+
+    Without a Climb, Doctor can only ask the machine-level questions. Which
+    model a subject would authenticate as, and which image it would run in, are
+    properties of a particular experiment rather than of the host.
+    """
+    if reference is None:
+        return None
+    return build_catalog_service(context).get_climb(reference).campaign
+
+
+def render_doctor_report(report: DoctorReport, console: Console) -> None:
+    """Print the environment facts and the check table."""
+    console.print(f"Techtree {report.versions['package_version']}")
+    console.print(f"Home:            {report.techtree_home}")
+    console.print(f"Host platform:   {report.host_platform or 'unsupported'}")
+    if report.docker_platform is not None:
+        console.print(f"Docker platform: {report.docker_platform}")
+
+    table = Table(box=None, pad_edge=False, padding=(0, 2))
+    table.add_column("Status", no_wrap=True)
+    table.add_column("Check", no_wrap=True)
+    table.add_column("Detail", overflow="fold")
+
+    for check in report.checks:
+        table.add_row(
+            Text(check.status.value, style=_STATUS_STYLE[check.status]),
+            check.label,
+            check.detail,
+        )
+
+    console.print()
+    console.print(table)
+
+
+def _render(data: object, console: Console) -> None:
+    """Adapt the report to the renderer signature the envelope layer uses."""
+    if isinstance(data, DoctorReport):
+        render_doctor_report(data, console)
+
+
+def _summary(total: int, blocking: int) -> str:
+    if blocking:
+        return f"{blocking} of {total} checks block Techtree from working here."
+    return f"All {total} checks ran and none of them block Techtree."
+
+
+def _blocking_error(blocking: list[DoctorCheck]) -> PrerequisiteError:
+    identifiers = [check.id for check in blocking]
+    return PrerequisiteError(
+        "this host is not ready: " + ", ".join(identifiers),
+        code="environment_not_ready",
+        details={"failed_checks": list(identifiers)},
+    )

techtree/cli/commands/engine.py

@@ -0,0 +1,207 @@
+"""``techtree engine install|status|verify``. Spec section 12.8.
+
+The commands are plumbing. Which engine this build ships, what installing one
+involves, and what counts as verified are the engine subsystem's decisions;
+these three functions choose an engine, call it, and hand the result to the
+envelope machinery.
+
+Choosing an engine follows one rule: an explicit digest wins, then the active
+engine, then the engine this build ships. That order is what makes
+``techtree engine status`` answer the question a person actually asked —
+"what am I about to run things with?" — without them having to name it.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from techtree.canonical import validate_digest
+from techtree.cli.context import CliContext, cli_context
+from techtree.cli.invoke import CommandResult, invoke_command
+from techtree.engines.bundle import default_engine_digest
+from techtree.engines.installer import EngineInstaller, find_uv
+from techtree.engines.registry import EngineRegistry
+from techtree.models.base import Digest
+from techtree.models.cli import CliMessage, MessageLevel, NextAction
+from techtree.models.engine import EngineStatus
+
+__all__ = [
+    "install_engine_command",
+    "render_engine_status",
+    "status_engine_command",
+    "verify_engine_command",
+]
+
+DigestArgument = Annotated[
+    str | None,
+    typer.Argument(
+        metavar="[DIGEST]",
+        help="The engine to act on. Defaults to the active or shipped engine.",
+    ),
+]
+
+
+def install_engine_command(ctx: typer.Context, digest: DigestArgument = None) -> None:
+    """Install the selected or default embedded engine."""
+    context = cli_context(ctx)
+
+    def action() -> CommandResult[EngineStatus]:
+        registry = EngineRegistry(context.paths, context.settings)
+        installer = EngineInstaller(context.paths, registry, find_uv())
+        # Reported before the install, which is what discards it. Decisions
+        # 0004, ratified as 0007 R7.
+        interrupted = installer.interrupted_installs()
+        status = installer.install(_requested(digest))
+
+        return CommandResult(
+            data=status,
+            messages=[
+                CliMessage(
+                    level=MessageLevel.INFO,
+                    code="engine_installed",
+                    text=(
+                        f"Evaluation engine {status.digest} is installed and "
+                        f"verified at {status.path}."
+                    ),
+                )
+            ],
+            warnings=[
+                CliMessage(
+                    level=MessageLevel.WARNING,
+                    code="engine_install_interrupted",
+                    text=(
+                        f"An earlier install of evaluation engine "
+                        f"{install.digest} did not finish. What it left behind "
+                        "was removed and the engine was installed again."
+                    ),
+                )
+                for install in interrupted
+            ],
+            next_actions=[_activate_or_browse(registry, status)],
+        )
+
+    invoke_command(context, "engine install", action, render_data=_render)
+
+
+def status_engine_command(ctx: typer.Context, digest: DigestArgument = None) -> None:
+    """Return installation and activation status."""
+    context = cli_context(ctx)
+
+    def action() -> CommandResult[EngineStatus]:
+        registry = EngineRegistry(context.paths, context.settings)
+        status = registry.status(_selected(context, digest))
+
+        return CommandResult(
+            data=status,
+            messages=[
+                CliMessage(
+                    level=MessageLevel.INFO,
+                    code="engine_status",
+                    text=f"Evaluation engine {status.digest} is {status.detail}.",
+                )
+            ],
+            next_actions=[
+                _activate_or_browse(registry, status)
+                if status.installed
+                else _install_action()
+            ],
+        )
+
+    invoke_command(context, "engine status", action, render_data=_render)
+
+
+def verify_engine_command(ctx: typer.Context, digest: DigestArgument = None) -> None:
+    """Recompute bundle and live-environment checks."""
+    context = cli_context(ctx)
+
+    def action() -> CommandResult[EngineStatus]:
+        registry = EngineRegistry(context.paths, context.settings)
+        installer = EngineInstaller(context.paths, registry, find_uv())
+        status = installer.verify(_selected(context, digest))
+
+        return CommandResult(
+            data=status,
+            messages=[
+                CliMessage(
+                    level=MessageLevel.INFO,
+                    code="engine_verified",
+                    text=(
+                        f"Evaluation engine {status.digest} holds the files it "
+                        "was installed with and runs the pinned validator."
+                    ),
+                )
+            ],
+            next_actions=[_activate_or_browse(registry, status)],
+        )
+
+    invoke_command(context, "engine verify", action, render_data=_render)
+
+
+def render_engine_status(status: EngineStatus, console: Console) -> None:
+    """Print one engine's state for a person."""
+    console.print(f"Engine:     {status.digest}")
+    console.print(f"Location:   {status.path}")
+    console.print(f"Installed:  {'yes' if status.installed else 'no'}")
+    console.print(f"Verified:   {'yes' if status.verified else 'no'}")
+    console.print(f"Active:     {'yes' if status.active else 'no'}")
+    if status.python_executable is not None:
+        console.print(f"Python:     {status.python_executable}")
+
+
+def _render(data: object, console: Console) -> None:
+    if isinstance(data, EngineStatus):
+        render_engine_status(data, console)
+
+
+def _requested(digest: str | None) -> Digest | None:
+    """Validate an explicitly requested digest."""
+    return None if digest is None else validate_digest(digest)
+
+
+def _selected(context: CliContext, digest: str | None) -> Digest:
+    """Return the engine a command without an argument is about."""
+    explicit = _requested(digest)
+    if explicit is not None:
+        return explicit
+    active = context.settings.active_engine_digest
+    if active is not None:
+        return active
+    return default_engine_digest()
+
+
+def _install_action() -> NextAction:
+    return NextAction(
+        id="install_engine",
+        label="Install the managed evaluation engine",
+        reason="Preparing or starting a Climb needs an installed, active engine.",
+        cli=["techtree", "engine", "install"],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=False,
+    )
+
+
+def _activate_or_browse(registry: EngineRegistry, status: EngineStatus) -> NextAction:
+    """Offer setup when the new engine is not the active one, else browsing."""
+    if registry.active_digest() == status.digest:
+        return NextAction(
+            id="list_climbs",
+            label="Browse the available Climbs",
+            reason="The evaluation engine is ready.",
+            cli=["techtree", "climb", "list"],
+            hermes_tool=None,
+            hermes_args=None,
+            requires_user_confirmation=False,
+        )
+    return NextAction(
+        id="run_setup",
+        label="Finish setting this machine up",
+        reason="The engine is installed but is not the active one yet.",
+        cli=["techtree", "setup"],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=False,
+    )