@ahmed-g-gad/apothem 0.1.1

package/src/apothem/cli/_cmd_diff.py

@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: MIT
+
+"""``apothem diff`` — preview pending configuration changes for a harness."""
+
+from __future__ import annotations
+
+import click
+
+import apothem.cli as _pkg
+from apothem.cli import main
+from apothem.cli._common_flags import (
+    common_options,
+    get_console,
+    resolve_format,
+)
+from apothem.cli._epilogs import _EP_DIFF
+from apothem.cli._helpers import (
+    _CliUserError,
+    _complete_harness,
+    _dry_run_plan,
+    _emit_expected_error,
+    _lifecycle_envelope,
+    _load_profile,
+    _materialization_error,
+    _profile_error,
+    _profile_option,
+    _project_option,
+    _resolve_profile_path,
+    _resolve_project_root,
+    _result_dicts,
+    _unknown_harness_error,
+    _warning_dicts,
+)
+from apothem.cli._json_formatter import emit_json
+from apothem.harnesses._shared.install_driver import (
+    MaterializationError,
+    operation_label,
+    preview_status,
+)
+from apothem.lib.profile import ProfileValidationError
+
+
+@main.command(epilog=_EP_DIFF)
+@click.option(
+    "--harness",
+    required=True,
+    metavar="NAME",
+    help="Harness adapter name to preview pending changes for.",
+    shell_complete=_complete_harness,
+)
+@_profile_option
+@_project_option
+@common_options
+def diff(
+    harness: str,
+    profile: str | None,
+    project: str | None,
+    quiet: bool,
+    verbose: bool,
+    output_format: str,
+    no_color: bool,
+    json_flag: bool,
+) -> None:
+    """Preview the pending configuration changes for a single harness."""
+    fmt = resolve_format(output_format, json_flag)
+    con = get_console(no_color=no_color, quiet=quiet)
+    profile_path = _resolve_profile_path(profile)
+    try:
+        if harness.strip().lower() == "all":
+            raise _unknown_harness_error(harness)
+        project_root = _resolve_project_root(project)
+        shared_profile = _load_profile(profile_path)
+        selected = _pkg._selected_harness_ids(
+            harness, shared_profile=None, apply_excludes=False
+        )
+        _pkg._require_project_for_selection(selected, project_root)
+        harness_id = selected[0]
+        entry = _pkg.get_harness_entry(harness_id)
+        adapter = _pkg._load_adapter_for_entry(entry)
+    except ProfileValidationError as exc:
+        _emit_expected_error(
+            command="diff",
+            fmt=fmt,
+            harness=harness,
+            profile_path=profile_path,
+            error=_profile_error(exc),
+        )
+        return
+    except _CliUserError as exc:
+        _emit_expected_error(
+            command="diff",
+            fmt=fmt,
+            harness=harness,
+            profile_path=profile_path,
+            error=exc.to_dict(),
+        )
+        return
+
+    try:
+        run = _dry_run_plan(entry, adapter, project_root, shared_profile)
+    except MaterializationError as exc:
+        _emit_expected_error(
+            command="diff",
+            fmt=fmt,
+            harness=harness,
+            profile_path=profile_path,
+            project_root=project_root,
+            error=_materialization_error(exc, files_written=[]),
+        )
+        return
+    except _CliUserError as exc:
+        _emit_expected_error(
+            command="diff",
+            fmt=fmt,
+            harness=harness,
+            profile_path=profile_path,
+            project_root=project_root,
+            error=exc.to_dict(),
+        )
+        return
+
+    if fmt == "json":
+        payload = _lifecycle_envelope(
+            status="dry_run",
+            command="diff",
+            action="dry_run",
+            harness=harness,
+            profile_path=profile_path,
+            project_root=project_root,
+            files_written=[],
+            results=_result_dicts(harness_id, run),
+            warnings=_warning_dicts(harness_id, run),
+            materialization=run,
+        )
+        emit_json(payload)
+        return
+
+    con.print(f"[bold]Pending changes for[/] [cyan]{harness_id}[/]:")
+    if verbose:
+        con.print(
+            "[dim]Preview only — nothing is written. Showing the full plan, "
+            "including unchanged targets and the raw operation kind and "
+            "outcome.[/]"
+        )
+    else:
+        con.print(
+            "[dim]Preview only — nothing is written. Each line is what "
+            "'apothem install' would do.[/]"
+        )
+    rendered = 0
+    had_results = False
+    for result in run.results:
+        had_results = True
+        # Warnings are surfaced elsewhere; a no-op target (e.g. nothing stale
+        # to prune) is not a pending change. Both are omitted from the default
+        # preview and restored under --verbose for the full plan.
+        if result.outcome == "warning" and not verbose:
+            continue
+        if result.outcome == "unchanged" and not verbose:
+            continue
+        rendered += 1
+        label = operation_label(result.operation)
+        status = preview_status(result.operation, result.outcome, dry_run=run.dry_run)
+        raw = f" [dim]\\[{result.operation}/{result.outcome}][/]" if verbose else ""
+        con.print(f"  [cyan]{label}[/] {result.path} [dim]({status})[/]{raw}")
+        diff_text = result.detail.get("diff")
+        if diff_text:
+            for line in diff_text.splitlines():
+                if line.startswith("+") and not line.startswith("+++"):
+                    con.print(f"    [green]{line}[/]")
+                elif line.startswith("-") and not line.startswith("---"):
+                    con.print(f"    [red]{line}[/]")
+                else:
+                    con.print(f"    [dim]{line}[/]")
+    if rendered == 0:
+        if had_results:
+            con.print(
+                "  [dim]No pending changes. Re-run with --verbose for the full plan.[/]"
+            )
+        else:
+            con.print("  [dim]No planned targets.[/]")

package/src/apothem/cli/_cmd_doctor.py

@@ -0,0 +1,143 @@
+# SPDX-License-Identifier: MIT
+
+"""``apothem doctor`` — system diagnostics for the Apothem installation."""
+
+from __future__ import annotations
+
+import sys
+
+from rich.table import Table
+
+import apothem.cli as _pkg
+from apothem.cli import (
+    _VERSION,
+    main,
+)
+from apothem.cli._common_flags import (
+    common_options,
+    get_console,
+    resolve_format,
+)
+from apothem.cli._epilogs import _EP_DOCTOR
+from apothem.cli._helpers import (
+    _EXIT_EXPECTED,
+    _resolve_profile_path,
+)
+from apothem.cli._json_formatter import emit_json
+from apothem.lib.profile import ProfileValidationError, load_profile_file
+
+
+@main.command(epilog=_EP_DOCTOR)
+@common_options
+def doctor(
+    quiet: bool,
+    verbose: bool,
+    output_format: str,
+    no_color: bool,
+    json_flag: bool,
+) -> None:
+    """Run system diagnostics for the Apothem installation."""
+    import platform
+
+    fmt = resolve_format(output_format, json_flag)
+    con = get_console(no_color=no_color, quiet=quiet)
+    adapters = _pkg._all_adapters()
+    # One adapter raising in is_installed() must not abort the diagnostic; it
+    # degrades to an error row and forces a non-zero exit.
+    harness_status: list[dict[str, object]] = []
+    errored = False
+    for adapter in adapters:
+        name = getattr(adapter, "name", type(adapter).__name__)
+        try:
+            harness_status.append({"name": name, "installed": adapter.is_installed()})
+        except Exception as exc:
+            errored = True
+            harness_status.append(
+                {
+                    "name": name,
+                    "installed": False,
+                    "error": f"{type(exc).__name__}: {exc}",
+                }
+            )
+
+    profile_path = _resolve_profile_path(None)
+    profile_exists = profile_path.exists()
+    # An existence check alone passes a present-but-malformed profile. Validate a
+    # present profile against the packaged schema with the same loader the
+    # `profile set` and install paths use, so a broken profile surfaces as a
+    # diagnostic failure (and a non-zero exit) instead of a green "found".
+    profile_valid: bool | None = None
+    profile_error: str | None = None
+    if profile_exists:
+        try:
+            load_profile_file(profile_path)
+            profile_valid = True
+        except ProfileValidationError as exc:
+            profile_valid = False
+            profile_error = str(exc)
+
+    profile_ok = not (profile_exists and profile_valid is False)
+    all_ok = (
+        (not errored) and profile_ok and all(s["installed"] for s in harness_status)
+    )
+
+    if fmt == "json":
+        payload: dict[str, object] = {
+            "version": _VERSION,
+            "python": sys.version.split()[0],
+            "platform": f"{platform.system()} {platform.release()}",
+            "profile_path": str(profile_path),
+            "profile_exists": profile_exists,
+            "profile_valid": profile_valid,
+            "harnesses": harness_status,
+            "all_ok": all_ok,
+        }
+        if profile_error is not None:
+            payload["profile_error"] = profile_error
+        emit_json(payload)
+        if not all_ok:
+            sys.exit(_EXIT_EXPECTED)
+        return
+
+    con.print("[bold]Apothem Doctor[/]")
+    con.print(f"  Version:   Apothem v{_VERSION}")
+    con.print(f"  Python:    {sys.version.split()[0]}")
+    con.print(f"  Platform:  {platform.system()} {platform.release()}")
+
+    if not profile_exists:
+        profile_note = "[yellow]missing[/]"
+    elif profile_valid:
+        profile_note = "[green]found, valid[/]"
+    else:
+        profile_note = "[red]found, invalid[/]"
+    con.print(f"  Profile:   {profile_path} [{profile_note}]")
+    if profile_valid is False and profile_error:
+        con.print(f"             [red]{profile_error}[/]")
+
+    table = Table(title="Harness Status", show_header=True, header_style="bold cyan")
+    table.add_column("Harness", style="cyan")
+    table.add_column("Installed", justify="center")
+
+    for status in harness_status:
+        if status.get("error"):
+            table.add_row(str(status["name"]), "[red]error[/]")
+            continue
+        installed = bool(status["installed"])
+        table.add_row(str(status["name"]), "[green]✓[/]" if installed else "[dim]-[/]")
+
+    con.print(table)
+
+    if all_ok:
+        con.print("[green]All checks passed.[/]")
+    elif not profile_ok:
+        con.print(
+            "[yellow]The shared profile is present but failed schema validation. "
+            "Fix the reported error, or re-scaffold it with 'apothem profile init'.[/]"
+        )
+        sys.exit(_EXIT_EXPECTED)
+    else:
+        con.print(
+            "[yellow]Some harnesses are not installed or could not be checked. "
+            "Run 'apothem install --harness <name>'.[/]"
+        )
+        sys.exit(_EXIT_EXPECTED)

package/src/apothem/cli/_cmd_harnesses.py

@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: MIT
+
+"""``apothem harnesses`` group — list and inspect registered adapters."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+from rich.table import Table
+
+import apothem.cli as _pkg
+from apothem.cli import main
+from apothem.cli._common_flags import (
+    common_options,
+    get_console,
+    resolve_format,
+)
+from apothem.cli._epilogs import (
+    _EP_HARNESSES_LIST,
+    _EP_HARNESSES_SHOW,
+)
+from apothem.cli._helpers import (
+    _CONTEXT,
+    _EXIT_EXPECTED,
+    _EXIT_PARTIAL,
+    _CliUserError,
+    _emit_expected_error,
+    _unknown_harness_error,
+)
+from apothem.cli._json_formatter import emit_json
+
+
+@main.group(context_settings=_CONTEXT)
+def harnesses() -> None:
+    """List and inspect registered harness adapters."""
+
+
+@harnesses.command("list", epilog=_EP_HARNESSES_LIST)
+@common_options
+def harnesses_list(
+    quiet: bool,
+    verbose: bool,
+    output_format: str,
+    no_color: bool,
+    json_flag: bool,
+) -> None:
+    """List all registered harness adapters."""
+    fmt = resolve_format(output_format, json_flag)
+    con = get_console(no_color=no_color, quiet=quiet)
+    adapters = _pkg._all_adapters()
+
+    # One adapter raising while reporting its status must not abort the listing;
+    # it becomes an error row and the command exits non-zero so the fault is
+    # observable.
+    entries: list[dict[str, object]] = []
+    errored = False
+    for adapter in adapters:
+        name = getattr(adapter, "name", type(adapter).__name__)
+        try:
+            entries.append(
+                {
+                    "name": name,
+                    "installed": adapter.is_installed(),
+                    "output_path": str(adapter.output_path),
+                }
+            )
+        except Exception as exc:
+            errored = True
+            entries.append(
+                {
+                    "name": name,
+                    "outcome": "error",
+                    "message": f"{type(exc).__name__}: {exc}",
+                }
+            )
+
+    listed_any = any("installed" in entry for entry in entries)
+    exit_code = 0
+    if errored:
+        exit_code = _EXIT_PARTIAL if listed_any else _EXIT_EXPECTED
+
+    if fmt == "json":
+        emit_json(entries)
+        if exit_code:
+            sys.exit(exit_code)
+        return
+
+    table = Table(
+        title="Registered Harness Adapters",
+        show_header=True,
+        header_style="bold cyan",
+    )
+    table.add_column("Name", style="cyan", no_wrap=True)
+    table.add_column("Installed", justify="center")
+    table.add_column("Output Path")
+
+    for entry in entries:
+        if entry.get("outcome") == "error":
+            table.add_row(
+                str(entry["name"]),
+                "[red]error[/]",
+                str(entry.get("message", "")),
+            )
+            continue
+        table.add_row(
+            str(entry["name"]),
+            "[green]✓[/]" if entry["installed"] else "[red]✗[/]",
+            str(entry["output_path"]),
+        )
+
+    con.print(table)
+    if exit_code:
+        sys.exit(exit_code)
+
+
+@harnesses.command("show", epilog=_EP_HARNESSES_SHOW)
+@click.argument("name")
+@common_options
+def harnesses_show(
+    name: str,
+    quiet: bool,
+    verbose: bool,
+    output_format: str,
+    no_color: bool,
+    json_flag: bool,
+) -> None:
+    """Show details for a specific harness adapter."""
+    fmt = resolve_format(output_format, json_flag)
+    con = get_console(no_color=no_color, quiet=quiet)
+    try:
+        entry = _pkg.get_harness_entry(name)
+        adapter = _pkg._load_adapter_for_entry(entry)
+    except KeyError:
+        error = _unknown_harness_error(name).to_dict()
+        _emit_expected_error(
+            command="harnesses show",
+            fmt=fmt,
+            harness=name,
+            error=error,
+        )
+        return
+    except _CliUserError as exc:
+        _emit_expected_error(
+            command="harnesses show",
+            fmt=fmt,
+            harness=name,
+            error=exc.to_dict(),
+        )
+        return
+
+    if fmt == "json":
+        emit_json(
+            {
+                "name": adapter.name,
+                "display_name": entry.display_name,
+                "scope": entry.scope,
+                "installed": adapter.is_installed(),
+                "output_path": str(adapter.output_path),
+            }
+        )
+    else:
+        con.print(f"  [bold]Name:[/]       {adapter.name}")
+        con.print(f"  [bold]Display:[/]    {entry.display_name}")
+        con.print(f"  [bold]Scope:[/]      {entry.scope}")
+        con.print(f"  [bold]Installed:[/]  {adapter.is_installed()}")
+        con.print(f"  [bold]Output:[/]     {adapter.output_path}")