superpowers-manager 0.1.4 → 0.2.0

package/scripts/core/validate-adapter-response.py

@@ -0,0 +1,284 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+ENVELOPE_KEYS = {"protocol", "operation", "ok", "messages", "result", "error"}
+MESSAGE_KEYS = {"channel", "text"}
+ERROR_KEYS = {"code", "message", "hints"}
+OWNERSHIP_KEYS = {"plugin", "marketplace"}
+VERIFICATION_HINT_KEYS = {"mismatch", "missing"}
+OPERATIONS = {"build", "inspect", "install", "uninstall"}
+FINGERPRINT_RE = re.compile(r"(?:[0-9a-fA-F]{7}|[0-9a-fA-F]{40})\Z")
+MAX_NESTING = 64
+MAX_RESPONSE_BYTES = 1_048_576
+
+
+class ProtocolError(ValueError):
+    pass
+
+
+def reject_constant(value: str) -> None:
+    raise ProtocolError(f"non-standard JSON constant: {value}")
+
+
+def reject_duplicate_keys(
+    pairs: list[tuple[str, object]],
+) -> dict[str, object]:
+    obj: dict[str, object] = {}
+    for key, value in pairs:
+        if key in obj:
+            raise ProtocolError("duplicate object key")
+        obj[key] = value
+    return obj
+
+
+def nesting_exceeds_limit(value: object) -> bool:
+    stack = [(value, 0)]
+    while stack:
+        current, depth = stack.pop()
+        if isinstance(current, dict):
+            next_depth = depth + 1
+            if next_depth > MAX_NESTING:
+                return True
+            stack.extend((child, next_depth) for child in current.values())
+        elif isinstance(current, list):
+            next_depth = depth + 1
+            if next_depth > MAX_NESTING:
+                return True
+            stack.extend((child, next_depth) for child in current)
+    return False
+
+
+def require_object(value: object, label: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise ProtocolError(f"{label} must be an object")
+    return value
+
+
+def require_exact_keys(value: dict[str, object], expected: set[str], label: str) -> None:
+    actual = set(value)
+    if actual != expected:
+        raise ProtocolError(
+            f"{label} keys must be {sorted(expected)}, got {sorted(actual)}"
+        )
+
+
+def contains_terminal_control(value: str) -> bool:
+    return any(
+        ord(character) < 0x20
+        or 0x7F <= ord(character) <= 0x9F
+        or 0xD800 <= ord(character) <= 0xDFFF
+        for character in value
+    )
+
+
+def require_non_empty_string(value: object, label: str) -> str:
+    if not isinstance(value, str) or not value or "\n" in value or "\r" in value:
+        raise ProtocolError(f"{label} must be a non-empty single-line string")
+    if contains_terminal_control(value):
+        raise ProtocolError(f"{label} must not contain terminal control characters")
+    return value
+
+
+def validate_messages(value: object) -> list[dict[str, str]]:
+    if not isinstance(value, list):
+        raise ProtocolError("messages must be an array")
+    messages: list[dict[str, str]] = []
+    for index, item in enumerate(value):
+        message = require_object(item, f"messages[{index}]")
+        require_exact_keys(message, MESSAGE_KEYS, f"messages[{index}]")
+        channel = message.get("channel")
+        if channel not in {"stdout", "stderr"}:
+            raise ProtocolError(f"messages[{index}].channel is invalid")
+        text = require_non_empty_string(message.get("text"), f"messages[{index}].text")
+        messages.append({"channel": str(channel), "text": text})
+    return messages
+
+
+def validate_error(value: object) -> dict[str, object]:
+    error = require_object(value, "error")
+    require_exact_keys(error, ERROR_KEYS, "error")
+    code = require_non_empty_string(error.get("code"), "error.code")
+    message = require_non_empty_string(error.get("message"), "error.message")
+    hints_value = error.get("hints")
+    if not isinstance(hints_value, list):
+        raise ProtocolError("error.hints must be an array")
+    hints = [
+        require_non_empty_string(hint, f"error.hints[{index}]")
+        for index, hint in enumerate(hints_value)
+    ]
+    return {"code": code, "message": message, "hints": hints}
+
+
+def validate_result(
+    operation: str, value: object, inspect_view: str | None
+) -> dict[str, object]:
+    result = require_object(value, "result")
+    if operation in {"build", "uninstall"}:
+        require_exact_keys(result, set(), f"{operation} result")
+        return {}
+    if operation == "inspect":
+        if inspect_view == "fingerprint":
+            require_exact_keys(result, {"view", "fingerprint"}, "inspect result")
+            if result.get("view") != "fingerprint":
+                raise ProtocolError("inspect result view must be fingerprint")
+            fingerprint = result.get("fingerprint")
+            if fingerprint is not None and (
+                not isinstance(fingerprint, str)
+                or FINGERPRINT_RE.fullmatch(fingerprint) is None
+            ):
+                raise ProtocolError("fingerprint must be null, 7 hex, or 40 hex")
+            return {"view": "fingerprint", "fingerprint": fingerprint}
+        if inspect_view == "ownership":
+            require_exact_keys(
+                result,
+                {"view", "resources", "legacy_resources", "identity_state"},
+                "inspect result",
+            )
+            if result.get("view") != "ownership":
+                raise ProtocolError("inspect result view must be ownership")
+            resources = require_object(result.get("resources"), "resources")
+            legacy_resources = require_object(
+                result.get("legacy_resources"), "legacy_resources"
+            )
+            for label, group in (
+                ("resources", resources),
+                ("legacy_resources", legacy_resources),
+            ):
+                require_exact_keys(group, OWNERSHIP_KEYS, label)
+                if not all(isinstance(group[key], bool) for key in OWNERSHIP_KEYS):
+                    raise ProtocolError(f"{label} values must be Boolean")
+            manager_present = any(resources.values())
+            legacy_present = any(legacy_resources.values())
+            expected_state = {
+                (False, False): "neither",
+                (True, False): "manager",
+                (False, True): "legacy",
+                (True, True): "both",
+            }[(manager_present, legacy_present)]
+            identity_state = result.get("identity_state")
+            if identity_state != expected_state:
+                raise ProtocolError(
+                    f"identity_state must be {expected_state} for the reported resources"
+                )
+            return {
+                "view": "ownership",
+                "resources": resources,
+                "legacy_resources": legacy_resources,
+                "identity_state": identity_state,
+            }
+        if inspect_view == "update-control":
+            require_exact_keys(
+                result,
+                {"view", "update_control"},
+                "update-control inspect result",
+            )
+            if result.get("view") != "update-control":
+                raise ProtocolError("inspect result view must be update-control")
+            value = result.get("update_control")
+            if value not in {"managed", "unsupported"}:
+                raise ProtocolError(
+                    "update-control value must be managed or unsupported"
+                )
+            return {"view": "update-control", "update_control": value}
+        raise ProtocolError(
+            "inspect view must be fingerprint or ownership, or update-control"
+        )
+    if operation == "install":
+        require_exact_keys(result, {"verification_hints"}, "install result")
+        hints = require_object(result.get("verification_hints"), "verification_hints")
+        unknown = set(hints) - VERIFICATION_HINT_KEYS
+        if unknown:
+            raise ProtocolError(f"unknown verification hint keys: {sorted(unknown)}")
+        normalized = {
+            key: require_non_empty_string(value, f"verification_hints.{key}")
+            for key, value in hints.items()
+        }
+        return {"verification_hints": normalized}
+    raise ProtocolError(f"unsupported operation: {operation}")
+
+
+def validate_envelope(
+    raw: object, operation: str, adapter_exit: int, inspect_view: str | None
+) -> tuple[list[dict[str, str]], dict[str, object] | None, dict[str, object] | None]:
+    envelope = require_object(raw, "response")
+    require_exact_keys(envelope, ENVELOPE_KEYS, "response")
+    protocol = envelope.get("protocol")
+    if type(protocol) is not int or protocol != 1:
+        raise ProtocolError("protocol must equal integer 1")
+    if envelope.get("operation") != operation:
+        raise ProtocolError("response operation does not match invocation")
+    ok = envelope.get("ok")
+    if not isinstance(ok, bool):
+        raise ProtocolError("ok must be Boolean")
+    messages = validate_messages(envelope.get("messages"))
+    if ok:
+        if adapter_exit != 0:
+            raise ProtocolError("successful response requires adapter exit 0")
+        if envelope.get("error") is not None:
+            raise ProtocolError("successful response error must be null")
+        result = validate_result(operation, envelope.get("result"), inspect_view)
+        return messages, result, None
+    if adapter_exit == 0:
+        raise ProtocolError("failure response requires nonzero adapter exit")
+    if envelope.get("result") is not None:
+        raise ProtocolError("failure response result must be null")
+    error = validate_error(envelope.get("error"))
+    return messages, None, error
+
+
+def replay(messages: list[dict[str, str]]) -> None:
+    for message in messages:
+        stream = sys.stdout if message["channel"] == "stdout" else sys.stderr
+        print(message["text"], file=stream)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--operation", choices=sorted(OPERATIONS), required=True)
+    parser.add_argument("--adapter-exit", type=int, required=True)
+    parser.add_argument("--response", type=Path, required=True)
+    parser.add_argument("--result", type=Path, required=True)
+    parser.add_argument(
+        "--inspect-view", choices=("fingerprint", "ownership", "update-control")
+    )
+    args = parser.parse_args()
+    try:
+        response_size = args.response.stat().st_size
+        if response_size > MAX_RESPONSE_BYTES:
+            raise ProtocolError(
+                f"response exceeds {MAX_RESPONSE_BYTES}-byte limit"
+            )
+        with args.response.open(encoding="utf-8") as handle:
+            raw = json.load(
+                handle,
+                parse_constant=reject_constant,
+                object_pairs_hook=reject_duplicate_keys,
+            )
+        if nesting_exceeds_limit(raw):
+            raise ProtocolError("response JSON nesting exceeds limit")
+        messages, result, error = validate_envelope(
+            raw, args.operation, args.adapter_exit, args.inspect_view
+        )
+        replay(messages)
+        if error is not None:
+            print(f"error: {error['message']}", file=sys.stderr)
+            for hint in error["hints"]:
+                print(f"hint: {hint}", file=sys.stderr)
+            return 1
+        with args.result.open("w", encoding="utf-8") as handle:
+            json.dump(result, handle, allow_nan=False, separators=(",", ":"))
+            handle.write("\n")
+        return 0
+    except (OSError, UnicodeError, json.JSONDecodeError, ProtocolError, RecursionError) as exc:
+        print(f"error: invalid adapter response: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/install

@@ -2,29 +2,24 @@
 set -eu
 
 root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
-. "$root/scripts/lib.sh"
+. "$root/scripts/core/common.sh"
+. "$root/scripts/core/provenance.sh"
+. "$root/scripts/core/status.sh"
+. "$root/scripts/core/lifecycle.sh"
+. "$root/scripts/core/adapter.sh"
 
-codex_bin="${SUPERPOWERS_CODEX:-codex}"
-refresh_mode="${SUPERPOWERS_INSTALL_REFRESH_MODE:-add-only}"
-
-spw_require_command "$codex_bin"
 spw_require_command python3
 
-case "$refresh_mode" in
-  add-only|remove-add) ;;
-  *) spw_die "unsupported SUPERPOWERS_INSTALL_REFRESH_MODE: $refresh_mode" ;;
-esac
-
-echo "Note: remove or disable conflicting Superpowers providers yourself before relying on manager-provided skills."
+echo "Note: remove or disable conflicting Superpowers providers yourself before relying on manager skills."
 
 # Prepare-before-mutate: probe, and (re)generate the plugin tree if it is
 # missing or stale — including validation — entirely before any Codex
 # marketplace or plugin mutation. A failed prepare leaves Codex untouched.
 probe_output=$(sh "$root/scripts/probe" --porcelain)
-identity_state=$(printf '%s\n' "$probe_output" | awk -F= '$1 == "identity_state" { print $2 }')
-[ -n "$identity_state" ] || spw_die "probe did not report Codex identity state"
+identity_state=$(spw_probe_field "$probe_output" identity_state)
+[ -n "$identity_state" ] || spw_die "probe did not report adapter identity state"
 spw_require_no_legacy_state "$identity_state"
-status=$(printf '%s\n' "$probe_output" | awk -F= '$1 == "status" { print $2 }')
+status=$(spw_probe_field "$probe_output" status)
 case "$status" in
   needs\ prepare)
     sh "$root/scripts/prepare"
@@ -40,19 +35,25 @@ esac
 desired_commit=$(spw_metadata_commit_or_empty "$root/plugins/superpowers/.superpowers-upstream.json" || true)
 [ -n "$desired_commit" ] || spw_die "generated metadata missing desired commit after prepare"
 
-# Reconcile the manager marketplace pointer to this package root, then always
-# run the Codex install step: `install` means "make Codex use this root" and
-# never skips it because the generated tree looks current.
-spw_reconcile_marketplace "$codex_bin" "$root"
-
-case "$refresh_mode" in
-  remove-add)
-    "$codex_bin" plugin remove "$SPW_PLUGIN_ID" || true
-    ;;
-esac
-
-if ! "$codex_bin" plugin add "$SPW_PLUGIN_ID"; then
-  spw_die "codex plugin add failed for $SPW_PLUGIN_ID"
+tmp_parent="${TMPDIR:-/tmp}"
+if ! install_workspace=$(spw_make_workspace "$tmp_parent" "superpowers-manager.install"); then
+  spw_die "cannot create install workspace under $tmp_parent"
+fi
+spw_install_workspace_trap "$install_workspace"
+
+TMPDIR="$install_workspace"
+export TMPDIR
+install_result="$install_workspace/install.json"
+inspect_result="$install_workspace/inspect.json"
+ownership_result="$install_workspace/ownership.json"
+update_control_result="$install_workspace/update-control.json"
+spw_inspect_ownership "$ownership_result"
+spw_inspect_update_control "$update_control_result"
+identity_state=$(spw_adapter_result_get "$ownership_result" "identity_state")
+update_control=$(spw_adapter_result_get "$update_control_result" "update_control")
+spw_require_no_legacy_state "$identity_state"
+spw_require_managed_update_control "$update_control"
+spw_adapter_install "$install_result" "$root"
+if ! spw_verify_installed_fingerprint "$desired_commit" "$install_result" "$inspect_result"; then
+  exit 1
 fi
-
-spw_verify_refresh "$desired_commit"

package/scripts/pin

@@ -0,0 +1,51 @@
+#!/bin/sh
+set -eu
+
+root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+. "$root/scripts/core/common.sh"
+. "$root/scripts/core/upstream.sh"
+. "$root/scripts/core/selection.sh"
+
+[ "$#" -eq 1 ] || spw_usage_error 'usage: superpowers-manager pin REF'
+requested_ref="$1"
+
+if spw_is_pinnable_tag "$requested_ref"; then
+  requested_kind=tag
+elif spw_is_full_commit "$requested_ref"; then
+  requested_kind=raw-commit
+else
+  spw_usage_error 'pin REF must be an exact v-prefixed SemVer tag or full 40-hex commit'
+fi
+
+spw_require_command python3
+state_path=$(spw_selection_state_path)
+tmp_parent="${TMPDIR:-/tmp}"
+if ! pin_workspace=$(spw_make_workspace "$tmp_parent" "superpowers-manager.pin"); then
+  spw_die "cannot create pin workspace under $tmp_parent"
+fi
+spw_install_workspace_trap "$pin_workspace"
+
+normalized="$pin_workspace/selection.json"
+spw_selection_state "$root" read \
+  --path="$state_path" --output="$normalized"
+
+source="${SUPERPOWERS_UPSTREAM_URL:-$SPW_UPSTREAM_URL_DEFAULT}"
+spw_selection_state "$root" \
+  validate-source --source="$source"
+
+if [ "$requested_kind" = tag ]; then
+  spw_require_command git
+  commit=$(spw_resolve_exact_tag "$source" "$requested_ref")
+  resolved_ref="$requested_ref"
+else
+  spw_require_command git
+  requested_ref=$(printf '%s' "$requested_ref" | tr '[:upper:]' '[:lower:]')
+  resolved_ref="$requested_ref"
+  commit=$(spw_verify_raw_commit "$source" "$requested_ref" "$pin_workspace")
+fi
+
+spw_selection_state "$root" write-pinned \
+  --path="$state_path" --source="$source" --requested-ref="$requested_ref" \
+  --resolved-ref="$resolved_ref" --commit="$commit"
+
+printf 'pinned upstream selection to %s at %s\n' "$requested_ref" "$commit"

package/scripts/prepare

@@ -2,54 +2,63 @@
 set -eu
 
 root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
-. "$root/scripts/lib.sh"
+. "$root/scripts/core/common.sh"
+. "$root/scripts/core/upstream.sh"
+. "$root/scripts/core/selection.sh"
+. "$root/scripts/core/provenance.sh"
+. "$root/scripts/core/lifecycle.sh"
+. "$root/scripts/core/adapter.sh"
 
-upstream_url="${SUPERPOWERS_UPSTREAM_URL:-$SPW_UPSTREAM_URL_DEFAULT}"
 cache_parent="${SUPERPOWERS_CACHE_DIR:-$root/.cache/upstream}"
-cache="$cache_parent/superpowers"
 plugin_root="${SUPERPOWERS_PLUGIN_ROOT:-$root/plugins/superpowers}"
 manifest_template="${SUPERPOWERS_MANIFEST_TEMPLATE:-$root/plugins/superpowers/.codex-plugin/plugin.template.json}"
-builtin_validator="$root/scripts/validate-generated-plugin.py"
 additional_validator="${SUPERPOWERS_VALIDATOR:-}"
+invocation_root=$(pwd -P)
+case "$cache_parent" in
+  /*) ;;
+  *) cache_parent="$invocation_root/$cache_parent" ;;
+esac
+case "$plugin_root" in
+  /*) ;;
+  *) plugin_root="$invocation_root/$plugin_root" ;;
+esac
+cache="$cache_parent/superpowers"
 tmp_parent=$(dirname "$plugin_root")
-tmp_plugin="$tmp_parent/.superpowers.tmp.$$"
-
-cleanup_tmp_plugin() {
-  status=$?
-  trap - 0 HUP INT TERM
-  rm -rf "$tmp_plugin" || :
-  exit "$status"
-}
-
-trap cleanup_tmp_plugin 0
-trap 'exit 129' HUP
-trap 'exit 130' INT
-trap 'exit 143' TERM
+mkdir -p "$tmp_parent"
+if ! prepare_workspace=$(spw_make_workspace "$tmp_parent" ".superpowers.prepare"); then
+  spw_die "cannot create prepare workspace under $tmp_parent"
+fi
+spw_install_workspace_trap "$prepare_workspace"
+tmp_plugin="$prepare_workspace/superpowers"
+adapter_result="$prepare_workspace/adapter-build.json"
 
-requested_ref=$(spw_config_ref "$root")
+TMPDIR="$prepare_workspace"
+export TMPDIR
 
-spw_require_command git
 spw_require_command python3
+spw_compute_effective_selection "$root" "$prepare_workspace"
+spw_require_command git
+spw_require_command "$SPW_ADAPTER"
 [ -f "$manifest_template" ] || spw_die "missing fallback manifest template: $manifest_template"
-[ -f "$builtin_validator" ] || spw_die "missing built-in plugin validator: $builtin_validator"
-
-resolved_record=$(spw_resolve_ref "$upstream_url" "$requested_ref")
-resolution_kind=$(printf '%s\n' "$resolved_record" | awk '{ print $1 }')
-resolved_ref=$(printf '%s\n' "$resolved_record" | awk '{ print $2 }')
-commit=$(printf '%s\n' "$resolved_record" | awk '{ print $3 }')
 
 mkdir -p "$cache_parent" "$tmp_parent"
-if [ -d "$cache/.git" ]; then
-  if ! git -C "$cache" fetch --tags --prune "$upstream_url"; then
-    spw_die "cannot fetch upstream repo: $upstream_url"
-  fi
+if [ "$SPW_SELECTION_MODE" = "pinned" ]; then
+  spw_fetch_exact_commit \
+    "$SPW_EFFECTIVE_SOURCE" "$SPW_DESIRED_COMMIT" "$cache" "$prepare_workspace"
 else
-  if ! git clone "$upstream_url" "$cache"; then
-    spw_die "cannot clone upstream repo: $upstream_url"
+  git_source=$(spw_git_safe_source "$SPW_EFFECTIVE_SOURCE")
+  if [ -d "$cache/.git" ]; then
+    if ! git -C "$cache" fetch --tags --prune -- "$git_source"; then
+      spw_die "cannot fetch upstream repo: $SPW_EFFECTIVE_SOURCE"
+    fi
+  else
+    if ! git clone -- "$git_source" "$cache"; then
+      spw_die "cannot clone upstream repo: $SPW_EFFECTIVE_SOURCE"
+    fi
   fi
 fi
-if ! git -C "$cache" checkout --detach "$commit" >/dev/null; then
-  spw_die "cannot check out upstream commit: $commit"
+if ! git -C "$cache" checkout --detach "$SPW_DESIRED_COMMIT" >/dev/null; then
+  spw_die "cannot check out upstream commit: $SPW_DESIRED_COMMIT"
 fi
 
 spw_require_upstream_path "$cache/skills" "skills/"
@@ -60,11 +69,6 @@ spw_require_upstream_path "$cache/CODE_OF_CONDUCT.md" "CODE_OF_CONDUCT.md"
 rm -rf "$tmp_plugin"
 mkdir -p "$tmp_plugin/.codex-plugin"
 upstream_manifest="$cache/.codex-plugin/plugin.json"
-if [ -f "$upstream_manifest" ]; then
-  cp "$upstream_manifest" "$tmp_plugin/.codex-plugin/plugin.json"
-else
-  cp "$manifest_template" "$tmp_plugin/.codex-plugin/plugin.json"
-fi
 
 spw_copy_path_if_present "$cache/skills" "$tmp_plugin/skills"
 spw_copy_path_if_present "$cache/assets" "$tmp_plugin/assets"
@@ -79,32 +83,26 @@ fi
 
 spw_write_metadata_json \
   "$tmp_plugin/.superpowers-upstream.json" \
-  "$upstream_url" \
-  "$requested_ref" \
-  "$resolved_ref" \
-  "$commit" \
+  "$SPW_EFFECTIVE_SOURCE" \
+  "$SPW_REQUESTED_REF" \
+  "$SPW_RESOLVED_REF" \
+  "$SPW_DESIRED_COMMIT" \
   "$upstream_manifest_version"
 
 manager_version=$(
-  spw_manifest_version_for_ref "$requested_ref" "$resolution_kind" "$resolved_ref" "$commit"
+  spw_manifest_version_for_ref \
+    "$SPW_REQUESTED_REF" "$SPW_RESOLUTION_KIND" \
+    "$SPW_RESOLVED_REF" "$SPW_DESIRED_COMMIT"
 )
-spw_apply_manifest_overlay \
-  "$tmp_plugin/.codex-plugin/plugin.json" \
-  "$manager_version"
-
-# The validator must inspect the exact complete tree that will be swapped.
-cp "$manifest_template" "$tmp_plugin/.codex-plugin/plugin.template.json"
-
-if ! python3 -S "$builtin_validator" \
-  --plugin-root "$tmp_plugin" \
-  --source "$upstream_url" \
-  --requested-ref "$requested_ref" \
-  --resolved-ref "$resolved_ref" \
-  --commit "$commit" \
-  --manifest-version "$manager_version" \
-  --upstream-manifest-version "$upstream_manifest_version"; then
-  spw_die "built-in generated plugin validation failed"
-fi
+spw_invoke_adapter build "$adapter_result" "" -- \
+  --upstream-root "$cache" \
+  --candidate-root "$tmp_plugin" \
+  --requested-ref "$SPW_REQUESTED_REF" \
+  --resolved-ref "$SPW_RESOLVED_REF" \
+  --commit "$SPW_DESIRED_COMMIT" \
+  --manager-version "$manager_version" \
+  --upstream-manifest-version "$upstream_manifest_version" \
+  --fallback-manifest "$manifest_template"
 
 if [ -n "$additional_validator" ]; then
   [ -f "$additional_validator" ] || \
@@ -114,23 +112,6 @@ if [ -n "$additional_validator" ]; then
   fi
 fi
 
-# Replace the live tree with a single atomic rename, keeping a backup so a
-# failed swap restores the previous working generated tree (the spec requires
-# that a failed prepare never destroy it). tmp_plugin is a same-filesystem
-# sibling of plugin_root, so the renames cannot fail mid-copy.
-backup="$tmp_parent/.superpowers.bak.$$"
-rm -rf "$backup"
-if [ -e "$plugin_root" ]; then
-  mv "$plugin_root" "$backup"
-fi
-if mv "$tmp_plugin" "$plugin_root"; then
-  rm -rf "$backup"
-else
-  if [ -e "$backup" ]; then
-    mv "$backup" "$plugin_root"
-  fi
-  rm -rf "$tmp_plugin"
-  spw_die "failed to install generated tree into $plugin_root; previous tree restored"
-fi
+spw_replace_generated_tree "$tmp_plugin" "$plugin_root"
 
-echo "prepared $resolved_ref at $commit"
+echo "prepared $SPW_RESOLVED_REF at $SPW_DESIRED_COMMIT"