@ahmed-g-gad/apothem 0.1.1

package/src/apothem/cli/_cmd_uninstall.py

@@ -0,0 +1,215 @@
+# SPDX-License-Identifier: MIT
+
+"""``apothem uninstall`` + the continuous-form aliases."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+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_UNINSTALL
+from apothem.cli._helpers import (
+    _EXIT_EXPECTED,
+    _EXIT_PARTIAL,
+    _adapter_failure_result,
+    _adapter_resolve_output_path,
+    _CliUserError,
+    _emit_expected_error,
+    _harness_option,
+    _invoke_with_project,
+    _lifecycle_envelope,
+    _project_option,
+    _resolve_project_root,
+)
+from apothem.cli._json_formatter import emit_json
+
+
+def _uninstall_impl(
+    harness: str,
+    yes: bool,
+    fmt: str,
+    quiet: bool,
+    no_color: bool,
+    project: str | None = None,
+) -> None:
+    """Shared body for ``uninstall`` and its continuous-form aliases."""
+    con = get_console(no_color=no_color, quiet=quiet)
+    try:
+        project_root = _resolve_project_root(project)
+        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 _CliUserError as exc:
+        _emit_expected_error(
+            command="uninstall",
+            fmt=fmt,
+            harness=harness,
+            error=exc.to_dict(),
+        )
+        return
+
+    results: list[dict[str, object]] = []
+    last_output_path: Path | None = None
+    errored = False
+    removed_any = False
+    for harness_id, adapter in adapters:
+        output_path = _adapter_resolve_output_path(adapter, project_root)
+        last_output_path = output_path
+        # A bad adapter degrades to a per-harness error result rather than
+        # aborting the batch (the confirm prompt's Abort still propagates).
+        try:
+            installed = bool(
+                _invoke_with_project(adapter.is_installed, project=project_root)
+            )
+            if not installed:
+                results.append(
+                    {
+                        "harness": harness_id,
+                        "outcome": "skipped",
+                        "operation": "uninstall",
+                        "path": str(output_path),
+                        "message": "not installed; no files removed",
+                    }
+                )
+                if fmt != "json":
+                    con.print(
+                        f"[dim]{harness_id} is not installed; nothing to remove.[/]"
+                    )
+                continue
+            if not yes:
+                click.confirm(
+                    f"Remove {harness_id} configuration at {output_path}?",
+                    abort=True,
+                )
+            _invoke_with_project(adapter.uninstall, project=project_root)
+        except click.Abort:
+            raise
+        except Exception as exc:
+            errored = True
+            results.append(
+                _adapter_failure_result(harness_id, "uninstall", output_path, exc)
+            )
+            if fmt != "json":
+                get_error_console(no_color=no_color).print(
+                    f"[red]✗[/] {harness_id} uninstall failed: {exc}"
+                )
+            continue
+        removed_any = True
+        results.append(
+            {
+                "harness": harness_id,
+                "outcome": "updated",
+                "operation": "uninstall",
+                "path": str(output_path),
+                "message": "managed files removed",
+            }
+        )
+        if fmt != "json":
+            con.print(f"[green]✓[/] Uninstalled [cyan]{harness_id}[/]")
+
+    exit_code = 0
+    if errored:
+        exit_code = _EXIT_PARTIAL if removed_any else _EXIT_EXPECTED
+    if fmt == "json":
+        status = (
+            "success"
+            if exit_code == 0
+            else ("partial" if exit_code == _EXIT_PARTIAL else "error")
+        )
+        emit_json(
+            _lifecycle_envelope(
+                status=status,
+                command="uninstall",
+                action="uninstalled",
+                harness=harness,
+                profile_path=None,
+                project_root=project_root,
+                files_written=[],
+                results=results,
+                warnings=[],
+                output_path=last_output_path if len(adapters) == 1 else None,
+            )
+        )
+    if exit_code:
+        sys.exit(exit_code)
+
+
+@main.command(epilog=_EP_UNINSTALL)
+@_harness_option
+@click.option("--yes", is_flag=True, help="Skip confirmation prompt.")
+@_project_option
+@common_options
+def uninstall(
+    harness: str,
+    yes: bool,
+    project: str | None,
+    quiet: bool,
+    verbose: bool,
+    output_format: str,
+    no_color: bool,
+    json_flag: bool,
+) -> None:
+    """Remove a harness adapter configuration."""
+    _uninstall_impl(
+        harness,
+        yes,
+        resolve_format(output_format, json_flag),
+        quiet,
+        no_color,
+        project=project,
+    )
+
+
+def _make_uninstalling_alias(name: str) -> click.Command:
+    """Build the ``Uninstalling`` / ``uninstalling`` continuous-form alias."""
+
+    @click.command(name=name, epilog=_EP_UNINSTALL, hidden=True)
+    @_harness_option
+    @click.option("--yes", is_flag=True, help="Skip confirmation prompt.")
+    @_project_option
+    @common_options
+    def _alias(
+        harness: str,
+        yes: bool,
+        project: str | None,
+        quiet: bool,
+        verbose: bool,
+        output_format: str,
+        no_color: bool,
+        json_flag: bool,
+    ) -> None:
+        """Alias for uninstall (continuous form). Identical behavior."""
+        _uninstall_impl(
+            harness,
+            yes,
+            resolve_format(output_format, json_flag),
+            quiet,
+            no_color,
+            project=project,
+        )
+
+    return _alias
+
+
+main.add_command(_make_uninstalling_alias("Uninstalling"))
+
+
+main.add_command(_make_uninstalling_alias("uninstalling"))

package/src/apothem/cli/_cmd_update.py

@@ -0,0 +1,397 @@
+# SPDX-License-Identifier: MIT
+
+"""``apothem update`` + ``rollback`` + the update continuous-form aliases."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import cast
+
+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_ROLLBACK,
+    _EP_UPDATE,
+)
+from apothem.cli._helpers import (
+    _EXIT_EXPECTED,
+    _EXIT_PARTIAL,
+    _adapter_resolve_output_path,
+    _CliUserError,
+    _emit_expected_error,
+    _harness_option,
+    _lifecycle_envelope,
+    _profile_option,
+    _project_option,
+    _resolve_project_root,
+)
+from apothem.cli._json_formatter import emit_json
+from apothem.cli._materialize import _materialize
+from apothem.harnesses._shared import install_driver
+from apothem.harnesses._shared.install_driver import MaterializationResult
+from apothem.lib import install_ledger
+from apothem.lib.install_ledger import LedgerRecord
+
+
+@main.command(epilog=_EP_UPDATE)
+@_harness_option
+@_profile_option
+@click.option("--dry-run", is_flag=True, help="Preview update without writing files.")
+@_project_option
+@common_options
+def update(
+    harness: str,
+    profile: str | None,
+    dry_run: bool,
+    project: str | None,
+    quiet: bool,
+    verbose: bool,
+    output_format: str,
+    no_color: bool,
+    json_flag: bool,
+) -> None:
+    """Re-install a harness adapter configuration from the current profile."""
+    _materialize(
+        harness,
+        profile,
+        dry_run,
+        "update",
+        "Updated",
+        fmt=resolve_format(output_format, json_flag),
+        quiet=quiet,
+        no_color=no_color,
+        project=project,
+        verbose=verbose,
+    )
+
+
+def _make_updating_alias(name: str) -> click.Command:
+    """Build the ``Updating`` / ``updating`` continuous-form alias."""
+
+    @click.command(name=name, epilog=_EP_UPDATE, hidden=True)
+    @_harness_option
+    @_profile_option
+    @click.option(
+        "--dry-run",
+        is_flag=True,
+        help="Preview update without writing files.",
+    )
+    @_project_option
+    @common_options
+    def _alias(
+        harness: str,
+        profile: str | None,
+        dry_run: bool,
+        project: str | None,
+        quiet: bool,
+        verbose: bool,
+        output_format: str,
+        no_color: bool,
+        json_flag: bool,
+    ) -> None:
+        """Alias for update (continuous form). Identical behavior."""
+        _materialize(
+            harness,
+            profile,
+            dry_run,
+            "update",
+            "Updated",
+            fmt=resolve_format(output_format, json_flag),
+            quiet=quiet,
+            no_color=no_color,
+            project=project,
+            verbose=verbose,
+        )
+
+    return _alias
+
+
+def _record_backup_timestamps(record: LedgerRecord) -> list[str]:
+    """Return the unique backup-timestamp dirs referenced by *record*'s targets.
+
+    Each recorded ``backup_ref`` is ``<BACKUP_ROOT>/<timestamp>/<harness>/<rel>``;
+    one install pass can straddle a second boundary (the backup-slug granularity),
+    so a record may reference more than one timestamp set. Targets created fresh
+    (no prior file) carry no ``backup_ref`` and contribute nothing. Returns the
+    timestamps oldest-first.
+    """
+    backup_root = install_driver.BACKUP_ROOT.resolve()
+    timestamps: set[str] = set()
+    for target in record.targets:
+        if not target.backup_ref:
+            continue
+        try:
+            relative = Path(target.backup_ref).resolve().relative_to(backup_root)
+        except ValueError:
+            continue
+        if relative.parts:
+            timestamps.add(relative.parts[0])
+    return sorted(timestamps)
+
+
+def _rollback_impl(
+    harness: str,
+    *,
+    install_id: str | None,
+    yes: bool,
+    fmt: str,
+    quiet: bool,
+    no_color: bool,
+    project: str | None,
+) -> None:
+    """Shared body for the ``rollback`` command.
+
+    Resolves the recorded install (the latest, or the supplied ``--install-id``)
+    for each selected harness, then restores each recorded backup set through
+    :func:`restore_backup`, reconstructing every target's pre-install bytes from
+    the Apothem backup root. Emits the standard lifecycle envelope.
+    """
+    con = get_console(no_color=no_color, quiet=quiet)
+    try:
+        project_root = _resolve_project_root(project)
+        selected = _pkg._selected_harness_ids(
+            harness, shared_profile=None, apply_excludes=False
+        )
+        _pkg._require_project_for_selection(selected, project_root)
+    except _CliUserError as exc:
+        _emit_expected_error(
+            command="rollback", fmt=fmt, harness=harness, error=exc.to_dict()
+        )
+        return
+
+    results: list[dict[str, object]] = []
+    restored_any = False
+    errored = False
+    last_output_path: Path | None = None
+    for harness_id in selected:
+        entry = _pkg.get_harness_entry(harness_id)
+        try:
+            adapter = _pkg._load_adapter_for_entry(entry)
+        except _CliUserError as exc:
+            _emit_expected_error(
+                command="rollback", fmt=fmt, harness=harness, error=exc.to_dict()
+            )
+            return
+        output_path = _adapter_resolve_output_path(adapter, project_root)
+        last_output_path = output_path
+        if entry.scope == "user":
+            install_root = output_path.parent
+            root_kwargs: dict[str, Path] = {"harness_root": install_root}
+        else:
+            install_root = cast(Path, project_root)
+            root_kwargs = {"project_root": install_root}
+
+        if install_id is not None:
+            record = install_ledger.find_record(
+                entry.package_key, install_id, root=install_root
+            )
+        else:
+            record = install_ledger.latest_record(entry.package_key, root=install_root)
+
+        if record is None:
+            reason = (
+                f"no install record with id {install_id!r}"
+                if install_id is not None
+                else "no recorded install to roll back"
+            )
+            no_record = _CliUserError(
+                code="rollback.no_record",
+                message="Nothing to roll back.",
+                field="install-id" if install_id is not None else "harness",
+                reason=f"{harness_id}: {reason}.",
+                fix="Run 'apothem install' first, or pass an --install-id that "
+                "appears in the harness ledger.",
+            )
+            if len(selected) == 1:
+                _emit_expected_error(
+                    command="rollback",
+                    fmt=fmt,
+                    harness=harness,
+                    error=no_record.to_dict(),
+                )
+                return
+            errored = True
+            results.append(
+                {
+                    "harness": harness_id,
+                    "outcome": "error",
+                    "operation": "rollback",
+                    "path": str(output_path),
+                    "message": no_record.message,
+                }
+            )
+            continue
+
+        timestamps = _record_backup_timestamps(record)
+        if not timestamps:
+            results.append(
+                {
+                    "harness": harness_id,
+                    "outcome": "skipped",
+                    "operation": "rollback",
+                    "path": str(output_path),
+                    "message": "install captured no backups (all targets were "
+                    "newly created); nothing to restore",
+                }
+            )
+            if fmt != "json":
+                con.print(
+                    f"[dim]{harness_id}: install {record.install_id} captured no "
+                    "backups; nothing to restore.[/]"
+                )
+            continue
+
+        if not yes:
+            click.confirm(
+                f"Roll back {harness_id} to the state before install "
+                f"{record.install_id}?",
+                abort=True,
+            )
+
+        # Scope the restore to exactly this record's recorded backups. The
+        # timestamp slug is second-granular, so a sibling install pass in the
+        # same second shares the <timestamp>/<harness>/ set; restoring the whole
+        # set would clobber that sibling's files.
+        record_refs = frozenset(
+            str(Path(target.backup_ref).resolve())
+            for target in record.targets
+            if target.backup_ref
+        )
+        target_results: list[MaterializationResult] = []
+        for timestamp in timestamps:
+            target_results.extend(
+                install_driver.restore_backup(
+                    entry.package_key,
+                    timestamp,
+                    only_refs=record_refs,
+                    **root_kwargs,
+                )
+            )
+        install_ledger.append_record(
+            LedgerRecord.create(
+                harness=entry.package_key,
+                root=install_root,
+                kind="rollback",
+                install_id=record.install_id,
+            )
+        )
+        for result in target_results:
+            if result.outcome in {"created", "updated"}:
+                restored_any = True
+            elif result.outcome == "error":
+                errored = True
+            entry_dict: dict[str, object] = {
+                "harness": harness_id,
+                "outcome": result.outcome,
+                "operation": "rollback",
+                "path": result.path,
+                "message": result.message,
+            }
+            if result.backup_path is not None:
+                entry_dict["backup_path"] = result.backup_path
+            results.append(entry_dict)
+        if fmt != "json":
+            con.print(
+                f"[green]✓[/] Rolled back [cyan]{harness_id}[/] to install "
+                f"[dim]{record.install_id}[/]"
+            )
+
+    exit_code = 0
+    if errored:
+        exit_code = _EXIT_PARTIAL if restored_any else _EXIT_EXPECTED
+    if fmt == "json":
+        status = (
+            "success"
+            if exit_code == 0
+            else ("partial" if exit_code == _EXIT_PARTIAL else "error")
+        )
+        emit_json(
+            _lifecycle_envelope(
+                status=status,
+                command="rollback",
+                action="rolled_back",
+                harness=harness,
+                profile_path=None,
+                project_root=project_root,
+                files_written=[
+                    str(item["path"])
+                    for item in results
+                    if item.get("outcome") in {"created", "updated"}
+                ],
+                results=results,
+                warnings=[],
+                output_path=last_output_path if len(selected) == 1 else None,
+            )
+        )
+    if exit_code:
+        sys.exit(exit_code)
+
+
+@main.command(epilog=_EP_ROLLBACK)
+@_harness_option
+@click.option(
+    "--install-id",
+    default=None,
+    metavar="ULID",
+    help="Roll back the named install pass (default: the latest recorded install).",
+)
+@click.option(
+    "--last",
+    is_flag=True,
+    help="Roll back the latest recorded install (the default; explicit form).",
+)
+@click.option("--yes", is_flag=True, help="Skip confirmation prompt.")
+@_project_option
+@common_options
+def rollback(
+    harness: str,
+    install_id: str | None,
+    last: bool,
+    yes: bool,
+    project: str | None,
+    quiet: bool,
+    verbose: bool,
+    output_format: str,
+    no_color: bool,
+    json_flag: bool,
+) -> None:
+    """Restore a harness to the state before its recorded install."""
+    if install_id is not None and last:
+        _emit_expected_error(
+            command="rollback",
+            fmt=resolve_format(output_format, json_flag),
+            harness=harness,
+            error=_CliUserError(
+                code="rollback.conflicting_selectors",
+                message="Pass at most one of --install-id and --last.",
+                field="install-id",
+                reason="--install-id selects a specific install; --last selects "
+                "the most recent. They are mutually exclusive.",
+                fix="Drop --last to roll back the given id, or drop --install-id "
+                "to roll back the latest.",
+            ).to_dict(),
+        )
+        return
+    _rollback_impl(
+        harness,
+        install_id=install_id,
+        yes=yes,
+        fmt=resolve_format(output_format, json_flag),
+        quiet=quiet,
+        no_color=no_color,
+        project=project,
+    )
+
+
+main.add_command(_make_updating_alias("Updating"))
+
+
+main.add_command(_make_updating_alias("updating"))