@ahmed-g-gad/apothem 0.1.1

package/src/apothem/cli/_helpers.py

@@ -0,0 +1,857 @@
+# SPDX-License-Identifier: MIT
+
+"""Shared helpers, constants, and the ``AliasedGroup`` for the apothem CLI.
+
+Carries the cross-command building blocks the per-command modules consume:
+the structured CLI-error type, the adapter protocol + load helpers, the
+profile read/write helpers, the lifecycle-envelope builders, harness
+selection, project-root resolution, and the drift/plan helpers. Extracted
+verbatim from the former monolithic ``cli/__init__.py``; the patchable-helper
+call sites inside selection/load helpers resolve through the ``apothem.cli``
+package (``_pkg``) so the test patch seams keep landing."""
+
+from __future__ import annotations
+
+import inspect
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Protocol, cast
+
+import click
+from click.shell_completion import CompletionItem
+from rich.console import Console
+
+import apothem.cli as _pkg
+from apothem.cli._json_formatter import emit_json
+from apothem.harnesses._shared import install_driver
+from apothem.harnesses._shared.install_driver import (
+    MaterializationError,
+    MaterializationResult,
+    MaterializationRun,
+    check_fidelity,
+    fidelity_is_faithful,
+    write_bytes_safely,
+)
+from apothem.lib.harness_registry import (
+    SUPPORTED_HARNESS_IDS,
+    HarnessRegistryEntry,
+    iter_harness_entries,
+    load_adapter_class,
+)
+from apothem.lib.profile import (
+    ProfileValidationError,
+    load_profile_file,
+    resolve_profile_path,
+)
+from apothem.schemas import profile_minimal_path
+
+console = Console(highlight=False)
+
+#: Shared Click context settings (``-h`` / ``--help`` aliases) for ``main`` and
+#: the ``profile`` / ``harnesses`` sub-groups.
+_CONTEXT = {"help_option_names": ["-h", "--help"]}
+
+
+_ADAPTER_LOAD_ERRORS = (ImportError, AttributeError, TypeError, OSError)
+
+
+_EXIT_EXPECTED = 1
+
+
+_EXIT_PARTIAL = 2
+
+
+class _CliUserError(Exception):
+    """Expected operator-facing CLI failure."""
+
+    def __init__(
+        self,
+        *,
+        code: str,
+        message: str,
+        field: str,
+        reason: str,
+        fix: str,
+        safe_value: object | None = None,
+        files_written: tuple[str, ...] = (),
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.field = field
+        self.reason = reason
+        self.fix = fix
+        self.safe_value = safe_value
+        self.files_written = files_written
+
+    def to_dict(self) -> dict[str, object]:
+        """Return the machine-readable error object."""
+        return {
+            "code": self.code,
+            "message": self.message,
+            "field": self.field,
+            "reason": self.reason,
+            "fix": self.fix,
+            "safe_value": self.safe_value,
+            "files_written": list(self.files_written),
+        }
+
+
+class _Adapter(Protocol):
+    @property
+    def name(self) -> str: ...
+    @property
+    def output_path(self) -> Path: ...
+    def install(self, profile: dict[str, Any]) -> object: ...
+    def update(self, profile: dict[str, Any]) -> object: ...
+    def uninstall(self) -> None: ...
+    def is_installed(self) -> bool: ...
+    def verify(self) -> bool: ...
+
+    # Optional project-scope extension (opt-in per adapter). Adapters
+    # that materialize into a project root rather than a user-scope
+    # configuration root declare ``requires_project = True`` and accept
+    # an optional ``project: Path | None`` keyword argument on their
+    # lifecycle methods. The CLI threads the operator-supplied
+    # ``--project <path>`` value through ``_materialize`` and routes it
+    # to the adapter only when the adapter's signature accepts it (via
+    # ``_invoke_with_project`` introspection).
+    requires_project: bool
+
+
+def _adapter_requires_project(adapter: _Adapter) -> bool:
+    """Return True iff *adapter* opts into the project-scope contract.
+
+    The opt-in is the literal boolean ``True`` on the ``requires_project``
+    attribute. Truthy non-boolean values (e.g., ``MagicMock`` instances
+    in unit-test fixtures, sentinel objects from incomplete adapter
+    stubs) do not satisfy the opt-in — explicit ratification is required.
+    """
+    return getattr(adapter, "requires_project", False) is True
+
+
+def _adapter_resolve_output_path(adapter: _Adapter, project: Path | None) -> Path:
+    """Resolve the adapter's output path, threading *project* when supported.
+
+    Project-scope adapters expose a ``resolve_output_path(project)``
+    method whose return is the concrete on-disk target under the
+    operator-supplied project root. Adapters without that method fall
+    back to the static ``output_path`` property — appropriate for
+    user-scope adapters whose target is determined by the harness's
+    home-rooted configuration directory.
+    """
+    resolve_fn = getattr(adapter, "resolve_output_path", None)
+    if callable(resolve_fn):
+        return cast(Path, resolve_fn(project))
+    return adapter.output_path
+
+
+def _stdin_is_interactive() -> bool:
+    """Whether an interactive confirmation may be prompted (a TTY is attached).
+
+    A dedicated seam (rather than an inline ``sys.stdin.isatty()``) so the
+    blast-radius confirmation gate is exercisable under the test runner, where
+    stdin is a replayed stream rather than a terminal.
+    """
+    return sys.stdin.isatty()
+
+
+def _path_is_within(target: Path, root: Path) -> bool:
+    """Return True iff *target* resolves inside *root* (lexical containment)."""
+    try:
+        target.resolve(strict=False).relative_to(root.resolve(strict=False))
+    except ValueError:
+        return False
+    return True
+
+
+def _partition_blast_radius(
+    adapters: list[tuple[str, _Adapter]],
+    project_root: Path | None,
+) -> tuple[list[tuple[str, Path]], list[tuple[str, Path]]]:
+    """Split adapter targets into (under-project, outside-project/home-rooted).
+
+    Project-scope adapters materialize under the supplied ``--project`` root;
+    user-scope adapters materialize under the operator's real home directory,
+    i.e. outside that root. The partition is by concrete on-disk containment so
+    the disclosure stays truthful even if a home target happens to fall inside
+    an unusual project root.
+    """
+    within: list[tuple[str, Path]] = []
+    outside: list[tuple[str, Path]] = []
+    for harness_id, adapter in adapters:
+        target = _adapter_resolve_output_path(adapter, project_root)
+        if project_root is not None and _path_is_within(target, project_root):
+            within.append((harness_id, target))
+        else:
+            outside.append((harness_id, target))
+    return within, outside
+
+
+def _render_blast_radius(
+    con: Console,
+    within: list[tuple[str, Path]],
+    outside: list[tuple[str, Path]],
+    project_root: Path | None,
+) -> None:
+    """Print the pre-write disclosure: targets grouped by project vs home root."""
+    total = len(within) + len(outside)
+    con.print(f"[bold]Apothem will write {total} configuration file(s):[/]")
+    width = max((len(hid) for hid, _ in [*within, *outside]), default=0)
+    if within:
+        con.print(f"  [cyan]Under the project root[/] ({project_root}):")
+        for harness_id, target in within:
+            con.print(f"    {harness_id.ljust(width)}  -> {target}")
+    if outside:
+        con.print("  [yellow]Under your home directory[/] (outside --project):")
+        for harness_id, target in outside:
+            con.print(f"    {harness_id.ljust(width)}  -> {target}")
+
+
+_PLACEHOLDER_IDENTITY: dict[str, str] = {
+    "name": "Example User",
+    "email": "dev@example.invalid",
+    "website": "https://example.invalid",
+    "github": "example-user",
+}
+
+
+def _placeholder_identity_fields(profile: dict[str, Any]) -> list[str]:
+    """Return the identity fields still set to their shipped placeholder value."""
+    identity = profile.get("identity")
+    if not isinstance(identity, dict):
+        return []
+    return [
+        field
+        for field, placeholder in _PLACEHOLDER_IDENTITY.items()
+        if str(identity.get(field, "")).strip() == placeholder
+    ]
+
+
+def _placeholder_advisory_entry(
+    profile_path: Path, fields: list[str]
+) -> dict[str, object]:
+    """Build the lifecycle-envelope advisory for an unpersonalized identity."""
+    return {
+        "harness": None,
+        "outcome": "advisory",
+        "operation": "placeholder_identity",
+        "path": str(profile_path),
+        "fields": list(fields),
+        "message": (
+            "Profile identity is still the scaffold placeholder ("
+            + ", ".join(fields)
+            + "); personalize it so a real identity is projected. Edit the "
+            + "profile or run 'apothem profile set identity.name \"Your Name\"'."
+        ),
+    }
+
+
+def _invoke_with_project(
+    fn: Callable[..., object], *args: object, project: Path | None
+) -> object:
+    """Invoke *fn* passing ``project=`` only when its signature accepts it.
+
+    Backward-compatible bridge: existing user-scope adapters declare
+    ``install(self, profile)`` / ``uninstall(self)`` and do not accept
+    a ``project`` parameter. Project-scope adapters declare
+    ``install(self, profile, project=None)`` and similar. Introspection
+    via ``inspect.signature`` lets the CLI thread the operator-supplied
+    project root to the adapters that consume it without breaking the
+    older signatures.
+    """
+    try:
+        sig = inspect.signature(fn)
+    except (TypeError, ValueError):
+        return fn(*args)
+    if "project" in sig.parameters:
+        return fn(*args, project=project)
+    return fn(*args)
+
+
+def _load_adapter(harness: str) -> _Adapter:
+    """Load a harness adapter by name from the central registry."""
+    try:
+        entry = _pkg.get_harness_entry(harness)
+    except KeyError as exc:
+        available = ", ".join(SUPPORTED_HARNESS_IDS)
+        raise click.ClickException(
+            f"Unknown harness {harness!r}. Available harnesses: {available}."
+        ) from exc
+    try:
+        return cast(_Adapter, load_adapter_class(entry)())
+    except _ADAPTER_LOAD_ERRORS as exc:
+        raise click.ClickException(
+            f"Failed to load harness {entry.public_id!r}: {exc}"
+        ) from exc
+
+
+def _all_adapters() -> list[_Adapter]:
+    """Return instances of all registered harness adapters.
+
+    A broken adapter is surfaced as a yellow warning and skipped rather
+    than silently dropped — the sweep still returns the healthy adapters
+    but the operator sees which ones failed to load.
+    """
+    adapters: list[_Adapter] = []
+    for entry in iter_harness_entries():
+        try:
+            adapters.append(cast(_Adapter, load_adapter_class(entry)()))
+        except _ADAPTER_LOAD_ERRORS as exc:
+            console.print(
+                f"[yellow]⚠[/]  Failed to load adapter {entry.public_id!r}: {exc}",
+                style="yellow",
+            )
+    return adapters
+
+
+def _resolve_profile_path(profile: str | None) -> Path:
+    """Return the shared-profile path."""
+    return resolve_profile_path(profile)
+
+
+def _complete_harness(
+    ctx: click.Context, param: click.Parameter, incomplete: str
+) -> list[CompletionItem]:
+    """Shell-completion callback for the ``--harness`` option.
+
+    Offers the fifteen registered public harness ids plus the batch token
+    ``all``, filtered to those beginning with the operator's partial input. The
+    candidate set is the static registry's public-id form (e.g. ``claude-code``),
+    so completion never drifts from the harnesses ``install``/``verify`` accept.
+    """
+    candidates = [*SUPPORTED_HARNESS_IDS, "all"]
+    return [
+        CompletionItem(candidate)
+        for candidate in candidates
+        if candidate.startswith(incomplete)
+    ]
+
+
+def _load_profile(profile_path: Path) -> dict[str, Any]:
+    """Load, validate, and normalize the shared profile YAML."""
+    return load_profile_file(profile_path).to_dict()
+
+
+def _write_profile_text_safely(
+    profile_path: Path,
+    text: str,
+    *,
+    operation: str,
+) -> MaterializationResult:
+    """Write a profile document through the shared atomic write boundary."""
+    result = write_bytes_safely(
+        profile_path,
+        text.encode("utf-8"),
+        install_root=profile_path.parent,
+        harness_name="profile",
+        operation=operation,
+    )
+    if result.outcome == "error":
+        raise _CliUserError(
+            code="profile.write_failed",
+            message="Apothem profile write failed.",
+            field="profile",
+            reason=result.message,
+            fix=(
+                "Choose a profile path inside a normal directory and check "
+                "file permissions."
+            ),
+        )
+    return result
+
+
+def _profile_error(exc: ProfileValidationError) -> dict[str, object]:
+    """Return the stable CLI error object for profile validation failures."""
+    return exc.diagnostic.to_dict()
+
+
+def _parse_set_value(raw: str) -> object:
+    """Parse a ``profile set`` VALUE without YAML scalar-coercion footguns.
+
+    Explicit structured input (a value whose first non-space char is ``[`` or
+    ``{``) is parsed as YAML so list/map nodes can be set. Explicit booleans
+    (``true``/``false``, case-insensitive) coerce to bool for the enforcement
+    flags. Every other scalar is preserved as a literal string — no
+    Norway-problem coercion of ``no``/``yes``/``on``/``off``, no date or number
+    coercion (``2024-01-01``, ``1.0`` stay strings). Schema validation, not
+    guesswork, decides whether the literal is acceptable.
+    """
+    import yaml
+
+    stripped = raw.strip()
+    if stripped[:1] in {"[", "{"}:
+        try:
+            return yaml.safe_load(raw)
+        except yaml.YAMLError:
+            return raw
+    if stripped.lower() in {"true", "false"}:
+        return stripped.lower() == "true"
+    return raw
+
+
+def _set_nested(data: dict[str, Any], dotted_key: str, value: object) -> dict[str, Any]:
+    """Assign *value* at the dotted path *dotted_key* within *data*.
+
+    Walks the addressed path, creating intermediate maps only along it, and
+    sets the leaf. A single key with no dot keeps whole-node behavior. Sibling
+    keys and unaddressed structure are preserved. Mutates and returns *data*.
+    """
+    parts = dotted_key.split(".")
+    node = data
+    for part in parts[:-1]:
+        existing = node.get(part)
+        if not isinstance(existing, dict):
+            existing = {}
+            node[part] = existing
+        node = existing
+    node[parts[-1]] = value
+    return data
+
+
+def _format_error_plain(
+    error: dict[str, object], *, profile_path: Path | None = None
+) -> str:
+    """Format an expected error with the diagnostic fields operators need."""
+    files = error.get("files_written", [])
+    if isinstance(files, list) and files:
+        files_written = ", ".join(str(item) for item in files)
+    else:
+        files_written = "none"
+    lines = [str(error.get("message", "Apothem command failed."))]
+    if profile_path is not None:
+        lines.append(f"Profile: {profile_path}")
+    lines.extend(
+        [
+            f"Field: {error.get('field', 'command')}",
+            f"Reason: {error.get('reason', 'unknown failure')}",
+            f"Fix: {error.get('fix', 'Review the command input and retry.')}",
+            f"Files written: {files_written}.",
+        ]
+    )
+    safe_value = error.get("safe_value")
+    if safe_value is not None:
+        lines.insert(-1, f"Safe value: {safe_value!r}")
+    return "\n".join(lines)
+
+
+def _error_envelope(
+    *,
+    command: str,
+    harness: str | None = None,
+    profile_path: Path | None = None,
+    project_root: Path | None = None,
+    error: dict[str, object],
+    files_written: list[str] | None = None,
+    results: list[dict[str, object]] | None = None,
+    warnings: list[dict[str, object]] | None = None,
+    status: str = "error",
+) -> dict[str, object]:
+    """Build the stable machine-readable lifecycle envelope."""
+    return {
+        "status": status,
+        "command": command,
+        "harness": harness,
+        "profile_path": str(profile_path) if profile_path is not None else None,
+        "project": str(project_root) if project_root is not None else None,
+        "files_written": files_written or [],
+        "results": results or [],
+        "warnings": warnings or [],
+        "error": error,
+    }
+
+
+def _emit_expected_error(
+    *,
+    command: str,
+    fmt: str,
+    error: dict[str, object],
+    harness: str | None = None,
+    profile_path: Path | None = None,
+    project_root: Path | None = None,
+    files_written: list[str] | None = None,
+    results: list[dict[str, object]] | None = None,
+    warnings: list[dict[str, object]] | None = None,
+    exit_code: int = _EXIT_EXPECTED,
+) -> None:
+    """Emit an expected failure as JSON or a Click-formatted plain error."""
+    status = "partial" if exit_code == _EXIT_PARTIAL else "error"
+    if fmt == "json":
+        emit_json(
+            _error_envelope(
+                command=command,
+                harness=harness,
+                profile_path=profile_path,
+                project_root=project_root,
+                error=error,
+                files_written=files_written,
+                results=results,
+                warnings=warnings,
+                status=status,
+            )
+        )
+        sys.exit(exit_code)
+    message = _format_error_plain(error, profile_path=profile_path)
+    if exit_code == _EXIT_EXPECTED:
+        raise click.ClickException(message)
+    # click.ClickException hard-codes exit 1; emit the same `Error:` prefix
+    # by hand and preserve a non-default (partial) exit code in plain mode,
+    # for parity with the JSON branch above — a partial outcome exits 2 in
+    # both formats, never 2 under --json and 1 in plain.
+    click.echo(f"Error: {message}", err=True)
+    sys.exit(exit_code)
+
+
+def _lifecycle_envelope(
+    *,
+    status: str,
+    command: str,
+    action: str,
+    harness: str | None,
+    profile_path: Path | None,
+    project_root: Path | None,
+    files_written: list[str],
+    results: list[dict[str, object]],
+    warnings: list[dict[str, object]],
+    output_path: Path | None = None,
+    materialization: MaterializationRun | None = None,
+) -> dict[str, object]:
+    """Build a stable success or dry-run envelope."""
+    payload: dict[str, object] = {
+        "status": status,
+        "command": command,
+        "action": action,
+        "harness": harness,
+        "profile_path": str(profile_path) if profile_path is not None else None,
+        "project": str(project_root) if project_root is not None else None,
+        "files_written": files_written,
+        "results": results,
+        "warnings": warnings,
+        "error": None,
+    }
+    if output_path is not None:
+        payload["output_path"] = str(output_path)
+    if materialization is not None:
+        payload["materialization"] = materialization.to_dict()
+    return payload
+
+
+def _result_dicts(
+    harness: str, materialization: MaterializationRun | None
+) -> list[dict[str, object]]:
+    """Return materialization result dictionaries tagged by public harness id."""
+    if materialization is None:
+        return []
+    return [
+        {"harness": harness, **result.to_dict()} for result in materialization.results
+    ]
+
+
+def _warning_dicts(
+    harness: str, materialization: MaterializationRun | None
+) -> list[dict[str, object]]:
+    """Return warning result dictionaries tagged by public harness id."""
+    if materialization is None:
+        return []
+    return [
+        {"harness": harness, **warning.to_dict()}
+        for warning in materialization.warnings
+    ]
+
+
+def _adapter_failure_result(
+    harness_id: str,
+    operation: str,
+    output_path: Path | None,
+    exc: Exception,
+) -> dict[str, object]:
+    """Return a per-harness error result for an adapter that raised mid-batch.
+
+    Adapter lifecycle code is the untrusted edge: one adapter raising must degrade
+    that harness to a recorded error and let the batch continue, mirroring the
+    install/_materialize error model rather than aborting with a bare traceback.
+    """
+    return {
+        "harness": harness_id,
+        "outcome": "error",
+        "operation": operation,
+        "path": str(output_path) if output_path is not None else None,
+        "message": f"{type(exc).__name__}: {exc}",
+    }
+
+
+def _load_adapter_for_entry(entry: HarnessRegistryEntry) -> _Adapter:
+    """Load an adapter for a registry entry with structured CLI errors."""
+    try:
+        return cast(_Adapter, load_adapter_class(entry)())
+    except _ADAPTER_LOAD_ERRORS as exc:
+        raise _CliUserError(
+            code="harness.load_failed",
+            message="Apothem adapter loading failed.",
+            field="harness",
+            reason=f"{entry.public_id}: {exc}",
+            fix="Reinstall Apothem or inspect the adapter package import.",
+        ) from exc
+
+
+def _unknown_harness_error(harness: str) -> _CliUserError:
+    """Return a structured unknown-harness error."""
+    available = ", ".join(SUPPORTED_HARNESS_IDS)
+    return _CliUserError(
+        code="harness.unknown",
+        message="Apothem validation failed.",
+        field="harness",
+        reason=f"{harness!r} is not a supported harness.",
+        fix=f"Use one of: {available}, or use 'all' for batch lifecycle commands.",
+    )
+
+
+def _selected_harness_ids(
+    harness: str, *, shared_profile: dict[str, Any] | None, apply_excludes: bool
+) -> list[str]:
+    """Resolve one harness or the deterministic registry-wide selection."""
+    requested = harness.strip().lower()
+    if requested == "all":
+        selected = list(SUPPORTED_HARNESS_IDS)
+        if apply_excludes and shared_profile is not None:
+            excluded = set(shared_profile.get("exclude_harnesses", []))
+            selected = [item for item in selected if item not in excluded]
+        if not selected:
+            raise _CliUserError(
+                code="harness.none_selected",
+                message="Apothem validation failed.",
+                field="harness",
+                reason="batch selection resolved to zero harnesses.",
+                fix="Remove at least one entry from exclude_harnesses or select a named harness.",
+            )
+        return selected
+    try:
+        return [_pkg.get_harness_entry(harness).public_id]
+    except KeyError as exc:
+        raise _unknown_harness_error(harness) from exc
+
+
+def _require_project_for_selection(
+    harness_ids: list[str], project_root: Path | None
+) -> None:
+    """Reject selected project-scope harnesses when no project root exists."""
+    project_scoped = [
+        harness_id
+        for harness_id in harness_ids
+        if _pkg.get_harness_entry(harness_id).scope == "project"
+    ]
+    if project_scoped and project_root is None:
+        joined = ", ".join(project_scoped)
+        raise _CliUserError(
+            code="project.required",
+            message="Apothem validation failed.",
+            field="project",
+            reason=f"project-scope harnesses require --project: {joined}.",
+            fix="Pass --project PATH or select only user-scope harnesses.",
+        )
+
+
+def _profile_scaffold_text() -> str:
+    """Return a schema-valid minimal profile scaffold."""
+    import yaml
+
+    data = yaml.safe_load(profile_minimal_path().read_text(encoding="utf-8"))
+    return yaml.safe_dump(data, sort_keys=False)
+
+
+class AliasedGroup(click.Group):
+    """Click group that resolves subcommands case-insensitively."""
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        cmd = super().get_command(ctx, cmd_name)
+        if cmd is not None:
+            return cmd
+        lower = cmd_name.lower()
+        matches = [n for n in self.list_commands(ctx) if n.lower() == lower]
+        if len(matches) == 1:
+            return super().get_command(ctx, matches[0])
+        if len(matches) > 1:
+            ctx.fail(f"Ambiguous command {cmd_name!r}: matches {sorted(matches)}")
+        return None
+
+
+def _resolve_project_root(project: str | None) -> Path | None:
+    """Resolve operator-supplied ``--project`` value to an absolute path."""
+    if project is None:
+        return None
+    project_root = Path(project).expanduser().resolve(strict=False)
+    if not project_root.exists():
+        raise _CliUserError(
+            code="project.not_found",
+            message="Apothem validation failed.",
+            field="project",
+            reason=f"project root does not exist: {project_root}",
+            fix="Create the project directory or pass an existing --project PATH.",
+        )
+    if not project_root.is_dir():
+        raise _CliUserError(
+            code="project.invalid_type",
+            message="Apothem validation failed.",
+            field="project",
+            reason=f"project root is not a directory: {project_root}",
+            fix="Pass a directory path as --project.",
+        )
+    return project_root
+
+
+_project_option = click.option(
+    "--project",
+    default=None,
+    metavar="PATH",
+    help=(
+        "Project root for project-scope harnesses (e.g., cursor). Required "
+        "by adapters that materialize into a project tree rather than a "
+        "user-scope configuration directory."
+    ),
+)
+
+# Shared `--harness` decorator for the lifecycle commands whose option is
+# byte-identical (install, uninstall, update, rollback, verify, and their
+# continuous-form aliases): required, name-or-'all', shell-completed. The
+# `diff` and `quickstart` variants differ (distinct help, and quickstart's
+# `default="all"`) and declare their own `--harness` inline, so this is the
+# single source of truth only for the identical form.
+_harness_option = click.option(
+    "--harness",
+    required=True,
+    metavar="NAME",
+    help="Harness adapter name or 'all' for every supported harness.",
+    shell_complete=_complete_harness,
+)
+
+# Shared `--profile` decorator for every command that resolves the shared
+# profile (install, update, diff, verify, status, profile show/init/set/edit,
+# and the continuous-form aliases): an optional path to the shared profile
+# YAML, defaulting to the host's standard location when omitted. The single
+# source of truth so the flag surface stays uniform across the lifecycle.
+_profile_option = click.option(
+    "--profile",
+    default=None,
+    metavar="PATH",
+    help="Path to shared profile YAML.",
+)
+
+
+def _require_project_if_needed(
+    adapter: _Adapter, harness: str, project_root: Path | None
+) -> None:
+    """Reject a project-scope adapter invoked without ``--project``.
+
+    Project-scope adapters (``requires_project = True``) materialize into
+    an operator-supplied project tree; every lifecycle command must be
+    told where that tree is. User-scope adapters are unaffected.
+    """
+    if _adapter_requires_project(adapter) and project_root is None:
+        raise _CliUserError(
+            code="project.required",
+            message="Apothem validation failed.",
+            field="project",
+            reason=(f"{harness!r} materializes a project-scope configuration surface."),
+            fix="Pass --project PATH for this harness.",
+        )
+
+
+def _harness_roots(
+    entry: HarnessRegistryEntry,
+    adapter: _Adapter,
+    project_root: Path | None,
+) -> tuple[Path | None, Path | None]:
+    """Resolve the (harness_root, project_root) pair the install driver consumes.
+
+    The shared ``install_driver`` seams (``run_install`` / ``check_fidelity``)
+    take a user-scope ``harness_root`` (the home-rooted configuration directory)
+    XOR a project-scope ``project_root``. Project-scope adapters thread the
+    operator-supplied ``--project`` value; user-scope adapters resolve their
+    home root as the parent of the adapter's static ``output_path``.
+    """
+    if entry.scope == "project":
+        return None, project_root
+    return _adapter_resolve_output_path(adapter, project_root).parent, None
+
+
+def _drift_state(
+    entry: HarnessRegistryEntry,
+    adapter: _Adapter,
+    installed: bool,
+    project_root: Path | None,
+    shared_profile: dict[str, Any],
+) -> str:
+    """Classify a harness's profile-fidelity drift for the ``status`` command.
+
+    ``absent`` when the adapter reports no install; otherwise the profile
+    fidelity verdict — ``in-sync`` when every projected anchor carries the
+    freshly-projected profile body verbatim, else ``drift``. The check is
+    read-only: it re-projects the profile in memory and compares against the
+    on-disk anchors, mutating nothing.
+    """
+    if not installed:
+        return "absent"
+    harness_root, scoped_project = _harness_roots(entry, adapter, project_root)
+    results = check_fidelity(
+        entry.package_key,
+        harness_root=harness_root,
+        project_root=scoped_project,
+        profile=shared_profile,
+    )
+    return "in-sync" if fidelity_is_faithful(results) else "drift"
+
+
+def _dry_run_plan(
+    entry: HarnessRegistryEntry,
+    adapter: _Adapter,
+    project_root: Path | None,
+    shared_profile: dict[str, Any],
+) -> MaterializationRun:
+    """Return the no-write dry-run plan for one harness, diffs included.
+
+    Routes through the same ``install_driver.run_install(dry_run=True, profile=…)``
+    seam the install path uses, so the result carries the unified diff already
+    present in each operator-owned target's ``.detail`` — no re-derivation.
+    """
+    harness_root, scoped_project = _harness_roots(entry, adapter, project_root)
+    return install_driver.run_install(
+        entry.package_key,
+        harness_root=harness_root,
+        project_root=scoped_project,
+        dry_run=True,
+        profile=shared_profile,
+    )
+
+
+def _materialization_error(
+    exc: MaterializationError, *, files_written: list[str]
+) -> dict[str, object]:
+    """Convert a materialization exception to the CLI diagnostic contract."""
+    first = exc.run.errors[0] if exc.run.errors else None
+    return _CliUserError(
+        code="materialization.failed",
+        message="Apothem materialization failed.",
+        field=first.operation if first is not None else "materialization",
+        reason=first.message if first is not None else str(exc),
+        fix="Review the target path, permissions, and harness support files before retrying.",
+        files_written=tuple(files_written),
+    ).to_dict()
+
+
+def _configure_stdio() -> None:
+    """Force UTF-8 stdio on Windows so Rich output renders correctly.
+
+    Runs at CLI invocation only — never at import time — so it cannot
+    disturb a host process's captured streams. ``reconfigure`` mutates
+    the existing stream in place rather than replacing ``sys.stdout``,
+    which would orphan and later close a wrapping process's buffer
+    (e.g. pytest's capture buffer).
+    """
+    if sys.platform != "win32":
+        return
+    for stream_name in ("stdout", "stderr"):
+        stream = getattr(sys, stream_name)
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(encoding="utf-8", errors="replace")