@ahmed-g-gad/apothem 0.1.1

package/src/apothem/cli/_cmd_verify.py

@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: MIT
+
+"""``apothem verify`` — verify a harness adapter installation."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import apothem.cli as _pkg
+from apothem.cli import main
+from apothem.cli._common_flags import (
+    common_options,
+    get_console,
+    get_error_console,
+    resolve_format,
+)
+from apothem.cli._epilogs import _EP_VERIFY
+from apothem.cli._helpers import (
+    _EXIT_EXPECTED,
+    _adapter_failure_result,
+    _adapter_resolve_output_path,
+    _CliUserError,
+    _drift_state,
+    _emit_expected_error,
+    _harness_option,
+    _invoke_with_project,
+    _lifecycle_envelope,
+    _load_profile,
+    _profile_error,
+    _profile_option,
+    _project_option,
+    _resolve_profile_path,
+    _resolve_project_root,
+)
+from apothem.cli._json_formatter import emit_json
+from apothem.lib.profile import ProfileValidationError
+
+
+@main.command(epilog=_EP_VERIFY)
+@_harness_option
+@_profile_option
+@_project_option
+@common_options
+def verify(
+    harness: str,
+    profile: str | None,
+    project: str | None,
+    quiet: bool,
+    verbose: bool,
+    output_format: str,
+    no_color: bool,
+    json_flag: bool,
+) -> None:
+    """Verify a harness adapter installation.
+
+    Without ``--profile`` the check is structural: every managed target must be
+    present and valid. With ``--profile`` the check additionally requires
+    profile fidelity, so a present-but-drifted install fails verify — answering
+    "is THIS profile faithfully installed?" rather than merely "does it exist?".
+    """
+    fmt = resolve_format(output_format, json_flag)
+    con = get_console(no_color=no_color, quiet=quiet)
+    profile_path = _resolve_profile_path(profile) if profile is not None else None
+    try:
+        project_root = _resolve_project_root(project)
+        shared_profile: dict[str, Any] | None = (
+            _load_profile(profile_path) if profile_path is not None else None
+        )
+        selected = _pkg._selected_harness_ids(
+            harness, shared_profile=None, apply_excludes=False
+        )
+        _pkg._require_project_for_selection(selected, project_root)
+        adapters = [
+            (
+                harness_id,
+                _pkg._load_adapter_for_entry(_pkg.get_harness_entry(harness_id)),
+            )
+            for harness_id in selected
+        ]
+    except ProfileValidationError as exc:
+        _emit_expected_error(
+            command="verify",
+            fmt=fmt,
+            harness=harness,
+            profile_path=profile_path,
+            error=_profile_error(exc),
+        )
+        return
+    except _CliUserError as exc:
+        _emit_expected_error(
+            command="verify",
+            fmt=fmt,
+            harness=harness,
+            profile_path=profile_path,
+            error=exc.to_dict(),
+        )
+        return
+
+    results: list[dict[str, object]] = []
+    last_output_path: Path | None = None
+    all_verified = True
+    for harness_id, adapter in adapters:
+        output_path = _adapter_resolve_output_path(adapter, project_root)
+        last_output_path = output_path
+        try:
+            installed = bool(
+                _invoke_with_project(adapter.is_installed, project=project_root)
+            )
+            verified_struct = bool(
+                _invoke_with_project(adapter.verify, project=project_root)
+            )
+            drift: str | None = None
+            if shared_profile is not None:
+                entry = _pkg.get_harness_entry(harness_id)
+                drift = _drift_state(
+                    entry, adapter, installed, project_root, shared_profile
+                )
+        except Exception as exc:
+            all_verified = False
+            failure = _adapter_failure_result(harness_id, "verify", output_path, exc)
+            failure["installed"] = False
+            failure["verified"] = False
+            if shared_profile is not None:
+                failure["drift"] = "error"
+            results.append(failure)
+            if fmt != "json":
+                get_error_console(no_color=no_color).print(
+                    f"[red]✗[/] [cyan]{harness_id}[/] verify failed: {exc}"
+                )
+            continue
+        # With --profile the verdict is structural presence AND profile
+        # fidelity: a present-but-drifted install fails verify so a chosen
+        # profile is confirmed faithfully installed, not merely present.
+        verified = verified_struct and drift != "drift"
+        all_verified = all_verified and verified
+        outcome = "unchanged" if verified else "error"
+        if not verified_struct:
+            message = "managed targets missing or invalid"
+        elif drift == "drift":
+            message = "managed targets present but drifted from the profile"
+        elif shared_profile is not None:
+            message = "managed targets verified and profile-faithful"
+        else:
+            message = "managed targets verified"
+        row: dict[str, object] = {
+            "harness": harness_id,
+            "outcome": outcome,
+            "operation": "verify",
+            "path": str(output_path),
+            "message": message,
+            "installed": installed,
+            "verified": verified,
+        }
+        if drift is not None:
+            row["drift"] = drift
+        results.append(row)
+        if fmt != "json":
+            if verified:
+                con.print(
+                    f"[green]✓[/] [cyan]{harness_id}[/] is verified at {output_path}"
+                )
+            elif verified_struct and drift == "drift":
+                con.print(
+                    f"[red]✗[/] [cyan]{harness_id}[/] is installed but drifted "
+                    f"from the profile at {output_path}"
+                )
+            else:
+                con.print(
+                    f"[red]✗[/] [cyan]{harness_id}[/] is NOT verified "
+                    f"(expected path: {output_path})"
+                )
+
+    if fmt == "json":
+        payload = _lifecycle_envelope(
+            status="success" if all_verified else "error",
+            command="verify",
+            action="verified",
+            harness=harness,
+            profile_path=profile_path,
+            project_root=project_root,
+            files_written=[],
+            results=results,
+            warnings=[],
+            output_path=last_output_path if len(adapters) == 1 else None,
+        )
+        if len(results) == 1:
+            payload["installed"] = results[0]["installed"]
+            payload["verified"] = results[0]["verified"]
+        emit_json(payload)
+
+    if not all_verified:
+        sys.exit(_EXIT_EXPECTED)

package/src/apothem/cli/_common_flags.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+
+"""Shared Click options + console factory for the apothem CLI.
+
+Every subcommand in :mod:`apothem.cli` decorates itself with
+:func:`common_options` to receive the standard cross-subcommand flag set:
+``--quiet/-q``, ``--verbose/-v``, ``--format``, ``--no-color``, ``--json``
+(shorthand for ``--format json``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import click
+from rich.console import Console
+
+
+def common_options(f: Callable[..., Any]) -> Callable[..., Any]:
+    """Apply the standard cross-subcommand flag set to *f*.
+
+    Click stacks decorators bottom-up, so the order in which the
+    options appear in ``--help`` output is the *reverse* of the order
+    they are applied here. To get ``--quiet, --verbose, --format,
+    --no-color, --json`` in that visible order, the decorators below
+    are applied in reverse.
+    """
+    f = click.option(
+        "--json",
+        "json_flag",
+        is_flag=True,
+        default=False,
+        help="Shorthand for --format json.",
+    )(f)
+    f = click.option(
+        "--no-color",
+        is_flag=True,
+        default=False,
+        help="Disable ANSI color codes in output.",
+    )(f)
+    f = click.option(
+        "--format",
+        "output_format",
+        type=click.Choice(["plain", "json"], case_sensitive=False),
+        default="plain",
+        show_default=True,
+        help="Output format.",
+    )(f)
+    f = click.option(
+        "--verbose",
+        "-v",
+        is_flag=True,
+        default=False,
+        help="Emit additional diagnostic output.",
+    )(f)
+    return click.option(
+        "--quiet",
+        "-q",
+        is_flag=True,
+        default=False,
+        help="Suppress informational output; only errors are emitted.",
+    )(f)
+
+
+def get_console(no_color: bool = False, quiet: bool = False) -> Console:
+    """Return a Rich :class:`Console` honoring ``--no-color`` and ``--quiet``."""
+    if quiet:
+        return Console(highlight=False, quiet=True)
+    if no_color:
+        return Console(highlight=False, no_color=True)
+    return Console(highlight=False)
+
+
+def get_error_console(no_color: bool = False) -> Console:
+    """Return a Rich error :class:`Console` that writes to stderr and is never quiet.
+
+    ``--quiet`` suppresses informational output but the documented contract is
+    that errors are still emitted; an error console that ignores ``quiet`` and
+    targets stderr (the conventional error stream) honors that contract so a
+    batch failure under ``-q`` is never silent.
+    """
+    return Console(stderr=True, highlight=False, no_color=no_color)
+
+
+def resolve_format(output_format: str, json_flag: bool) -> str:
+    """Return ``"json"`` when ``--json`` is set or ``--format json`` was chosen, else ``"plain"``."""
+    if json_flag:
+        return "json"
+    return output_format

package/src/apothem/cli/_epilogs.py

@@ -0,0 +1,296 @@
+# SPDX-License-Identifier: MIT
+
+"""Per-subcommand ``--help`` epilog blocks for the apothem CLI.
+
+Each block carries Examples, Related commands, and Exit codes. Extracted
+verbatim from the former monolithic ``cli/__init__.py`` so ``--help`` output
+is byte-identical.
+"""
+
+from __future__ import annotations
+
+_EP_INSTALL = """
+Examples:
+  apothem install --harness claude-code
+  apothem install --harness all --project .
+  apothem install --harness claude-code --dry-run
+  apothem install --harness cursor --profile ~/profile.yaml --json
+
+Related commands:
+  installing  Continuous-form alias for install
+  update      Re-apply current profile to a harness
+  uninstall   Remove a harness configuration
+  verify      Check installation status
+
+Exit codes:
+  0  Adapter installed successfully
+  1  Expected validation, profile, harness, project, or adapter error
+  2  Partial batch materialization after at least one write
+"""
+
+_EP_UNINSTALL = """
+Examples:
+  apothem uninstall --harness claude-code
+  apothem uninstall --harness all --project . --yes
+  apothem uninstall --harness claude-code --yes
+
+Related commands:
+  install      Install a harness configuration
+  uninstalling Continuous-form alias for uninstall
+  verify       Check installation status
+
+Exit codes:
+  0  Adapter uninstalled or was not installed
+  1  Harness not found or user aborted confirmation
+"""
+
+_EP_ROLLBACK = """
+Examples:
+  apothem rollback --harness claude-code --last
+  apothem rollback --harness claude-code --install-id 01J9Z…  --yes
+  apothem rollback --harness cursor --project . --last --json
+
+Related commands:
+  install    Install a harness configuration
+  uninstall  Remove a harness configuration
+  verify     Check installation status
+
+Exit codes:
+  0  Pre-install state restored from the recorded backups
+  1  No matching install record, unknown install-id, harness/project error,
+     or user aborted confirmation
+  2  Partial restore after at least one backup was restored
+"""
+
+_EP_UPDATE = """
+Examples:
+  apothem update --harness claude-code
+  apothem update --harness all --project .
+  apothem update --harness claude-code --dry-run
+
+Related commands:
+  install   Install a harness configuration
+  updating  Continuous-form alias for update
+  verify    Check installation status
+
+Exit codes:
+  0  Adapter updated successfully
+  1  Expected validation, profile, harness, project, or adapter error
+  2  Partial batch materialization after at least one write
+"""
+
+_EP_VERIFY = """
+Examples:
+  apothem verify --harness claude-code
+  apothem verify --harness all --project .
+  apothem verify --harness claude-code --profile ~/profile.yaml
+  apothem verify --harness claude-code --json
+
+Notes:
+  Without --profile the check is structural (targets present and valid).
+  With --profile it also requires fidelity: a drifted install fails verify.
+
+Related commands:
+  install Install a harness configuration
+  update  Re-apply current profile to a harness
+  status  Report install/verify/drift across every harness
+
+Exit codes:
+  0  Harness is verified (with --profile, also faithful to it)
+  1  Harness is not verified (missing/invalid, or drifted from --profile)
+"""
+
+_EP_STATUS = """
+Examples:
+  apothem status
+  apothem status --project .
+  apothem status --profile ~/profile.yaml
+  apothem status --json
+
+Notes:
+  --profile selects the drift baseline; without it the default profile
+  (~/.config/apothem/profile.yaml) is used.
+
+Related commands:
+  verify          Verify a specific harness installation
+  diff            Preview pending changes for a harness
+  harnesses list  List all registered harnesses
+
+Exit codes:
+  0  Status reported (drift is reported, not an error)
+  2  At least one adapter failed to report its status
+"""
+
+_EP_DIFF = """
+Examples:
+  apothem diff --harness claude-code
+  apothem diff --harness cursor --project .
+  apothem diff --harness claude-code --json
+
+Related commands:
+  status   Report install/verify/drift across every harness
+  verify   Verify a specific harness installation
+  install  Apply the previewed changes
+
+Exit codes:
+  0  Diff reported (pending changes are reported, not an error)
+  1  Expected validation, profile, harness, or project error
+"""
+
+_EP_DOCTOR = """
+Examples:
+  apothem doctor
+  apothem doctor --json
+
+Related commands:
+  harnesses list  List all registered harnesses
+  verify          Check a specific harness
+
+Exit codes:
+  0  All checks passed
+  1  One or more harnesses are not installed
+"""
+
+_EP_PROFILE_SHOW = """
+Examples:
+  apothem profile show
+  apothem profile show --json
+
+Related commands:
+  profile init  Create a schema-valid shared profile
+  profile set   Set a key in the shared profile
+  profile edit  Open the profile in the system editor
+
+Exit codes:
+  0  Success
+  1  Profile missing or invalid
+"""
+
+_EP_PROFILE_INIT = """
+Examples:
+  apothem profile init
+  apothem profile init --profile ./profile.yaml --force
+
+Related commands:
+  profile show  Display the shared profile
+  profile edit  Open the profile in the system editor
+
+Exit codes:
+  0  Profile scaffold created
+  1  Profile exists or cannot be written
+"""
+
+_EP_PROFILE_SET = """
+Examples:
+  apothem profile set identity.name "Ada Lovelace"
+  apothem profile set preferences.style concise
+  apothem profile set seriousness SHARED
+  apothem profile set enforcement.sprints true
+
+KEY is a dotted path into the profile; VALUE is stored literally (bare words are
+not coerced) except true/false and explicit [..]/{..} input. The result is
+validated against the schema before writing; an invalid set is refused.
+
+Related commands:
+  profile show  Display the shared profile
+  profile edit  Open the profile in the system editor
+
+Exit codes:
+  0  Key set successfully
+  2  Invalid key or value (profile unchanged)
+"""
+
+_EP_PROFILE_EDIT = """
+Examples:
+  apothem profile edit
+
+Related commands:
+  profile show  Display the shared profile
+  profile set   Set a key in the shared profile
+
+Exit codes:
+  0  Editor exited normally
+"""
+
+_EP_HARNESSES_LIST = """
+Examples:
+  apothem harnesses list
+  apothem harnesses list --json
+
+Related commands:
+  harnesses show  Show details for a specific harness
+  doctor          Run system diagnostics
+
+Exit codes:
+  0  Success
+"""
+
+_EP_HARNESSES_SHOW = """
+Examples:
+  apothem harnesses show claude-code
+  apothem harnesses show claude-code --json
+
+Related commands:
+  harnesses list  List all registered harnesses
+
+Exit codes:
+  0  Success
+  1  Harness not found
+"""
+
+_EP_COMPLETION = """
+Examples:
+  apothem completion bash >> ~/.bashrc
+  apothem completion zsh  >> ~/.zshrc
+  apothem completion fish > ~/.config/fish/completions/apothem.fish
+  apothem completion powershell >> $PROFILE
+
+Enabling completion is opt-in — this command only prints the script; it never
+edits your shell startup files. Append the output to the file shown above (or
+source it ad-hoc), then restart the shell.
+
+Exit codes:
+  0  Completion script emitted
+  2  Unsupported shell requested
+"""
+
+_EP_QUICKSTART = """
+Examples:
+  apothem quickstart
+  apothem quickstart --harness all --project . --yes
+  apothem quickstart --harness claude-code
+  apothem quickstart --json
+
+Related commands:
+  install   Materialize a harness from the shared profile
+  verify    Confirm an installation is live
+  doctor    Check environment + installation health
+
+Exit codes:
+  0  Guided run completed
+  1  Expected validation, profile, harness, project, or adapter error
+  2  Partial batch materialization after at least one write
+"""
+
+_EP_MIGRATE_WORKSPACE = """
+Examples:
+  apothem migrate-workspace
+  apothem migrate-workspace --project .
+  apothem migrate-workspace --dry-run --json
+
+Migrates a legacy per-harness data home (.apothem/<harness>/...) and a legacy
+.plans/ tree into the single shared .apothem/{plans,memory,learning,contexts}
+working directory. Per-harness memory/contexts/learning stores union-merge by
+id; learning signals concatenate-dedup; .plans/ moves under .apothem/plans/.
+Every consumed source is backed up first; a conflicting record is skipped, never
+overwritten. The migration is idempotent — re-running on a migrated tree is a
+no-op.
+
+Related commands:
+  install   Materialize a harness from the shared profile
+  status    Report installed harnesses + drift
+
+Exit codes:
+  0  Migration completed (or no legacy layout found)
+  1  Expected validation or project error
+"""