superpowers-manager 0.1.6 → 0.3.0

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

@@ -1,245 +0,0 @@
-#!/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
-
-
-class ProtocolError(ValueError):
-    pass
-
-
-def reject_constant(value: str) -> None:
-    raise ProtocolError(f"non-standard JSON constant: {value}")
-
-
-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,
-            }
-        raise ProtocolError("inspect view must be fingerprint or ownership")
-    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"))
-    args = parser.parse_args()
-    try:
-        with args.response.open(encoding="utf-8") as handle:
-            raw = json.load(handle, parse_constant=reject_constant)
-        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

@@ -1,60 +0,0 @@
-#!/bin/sh
-set -eu
-
-root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
-. "$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"
-
-spw_require_command python3
-
-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 adapter identity state"
-spw_require_no_legacy_state "$identity_state"
-status=$(printf '%s\n' "$probe_output" | awk -F= '$1 == "status" { print $2 }')
-case "$status" in
-  needs\ prepare)
-    sh "$root/scripts/prepare"
-    ;;
-  needs\ install|current)
-    ;;
-  *)
-    printf '%s\n' "$probe_output"
-    spw_die "unknown probe status: $status"
-    ;;
-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"
-
-tmp_parent="${TMPDIR:-/tmp}"
-if ! install_workspace=$(mktemp -d "$tmp_parent/superpowers-manager.install.XXXXXX"); then
-  spw_die "cannot create install workspace under $tmp_parent"
-fi
-cleanup_install_workspace() {
-  status=$?
-  trap - 0 HUP INT TERM
-  rm -rf "$install_workspace" || :
-  exit "$status"
-}
-trap cleanup_install_workspace 0
-trap 'exit 129' HUP
-trap 'exit 130' INT
-trap 'exit 143' TERM
-
-TMPDIR="$install_workspace"
-export TMPDIR
-install_result="$install_workspace/install.json"
-inspect_result="$install_workspace/inspect.json"
-spw_adapter_install "$install_result" "$root"
-if ! spw_verify_installed_fingerprint "$desired_commit" "$install_result" "$inspect_result"; then
-  exit 1
-fi

package/scripts/prepare

@@ -1,126 +0,0 @@
-#!/bin/sh
-set -eu
-
-root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
-. "$root/scripts/core/common.sh"
-. "$root/scripts/core/upstream.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}"
-plugin_root="${SUPERPOWERS_PLUGIN_ROOT:-$root/plugins/superpowers}"
-manifest_template="${SUPERPOWERS_MANIFEST_TEMPLATE:-$root/plugins/superpowers/.codex-plugin/plugin.template.json}"
-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")
-mkdir -p "$tmp_parent"
-if ! prepare_workspace=$(mktemp -d "$tmp_parent/.superpowers.prepare.XXXXXX"); then
-  spw_die "cannot create prepare workspace under $tmp_parent"
-fi
-tmp_plugin="$prepare_workspace/superpowers"
-adapter_result="$prepare_workspace/adapter-build.json"
-
-cleanup_tmp_plugin() {
-  status=$?
-  trap - 0 HUP INT TERM
-  rm -rf "$prepare_workspace" || :
-  exit "$status"
-}
-
-trap cleanup_tmp_plugin 0
-trap 'exit 129' HUP
-trap 'exit 130' INT
-trap 'exit 143' TERM
-
-TMPDIR="$prepare_workspace"
-export TMPDIR
-
-requested_ref=$(spw_config_ref "$root")
-
-spw_require_command git
-spw_require_command python3
-spw_require_command "$SPW_ADAPTER"
-[ -f "$manifest_template" ] || spw_die "missing fallback manifest template: $manifest_template"
-
-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
-else
-  if ! git clone "$upstream_url" "$cache"; then
-    spw_die "cannot clone upstream repo: $upstream_url"
-  fi
-fi
-if ! git -C "$cache" checkout --detach "$commit" >/dev/null; then
-  spw_die "cannot check out upstream commit: $commit"
-fi
-
-spw_require_upstream_path "$cache/skills" "skills/"
-spw_require_upstream_path "$cache/LICENSE" "LICENSE"
-spw_require_upstream_path "$cache/README.md" "README.md"
-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"
-
-spw_copy_path_if_present "$cache/skills" "$tmp_plugin/skills"
-spw_copy_path_if_present "$cache/assets" "$tmp_plugin/assets"
-spw_copy_path_if_present "$cache/LICENSE" "$tmp_plugin/LICENSE"
-spw_copy_path_if_present "$cache/README.md" "$tmp_plugin/README.md"
-spw_copy_path_if_present "$cache/CODE_OF_CONDUCT.md" "$tmp_plugin/CODE_OF_CONDUCT.md"
-
-upstream_manifest_version=""
-if [ -f "$upstream_manifest" ]; then
-  upstream_manifest_version=$(spw_json_get "$upstream_manifest" "version")
-fi
-
-spw_write_metadata_json \
-  "$tmp_plugin/.superpowers-upstream.json" \
-  "$upstream_url" \
-  "$requested_ref" \
-  "$resolved_ref" \
-  "$commit" \
-  "$upstream_manifest_version"
-
-manager_version=$(
-  spw_manifest_version_for_ref "$requested_ref" "$resolution_kind" "$resolved_ref" "$commit"
-)
-spw_invoke_adapter build "$adapter_result" "" -- \
-  --upstream-root "$cache" \
-  --candidate-root "$tmp_plugin" \
-  --requested-ref "$requested_ref" \
-  --resolved-ref "$resolved_ref" \
-  --commit "$commit" \
-  --manager-version "$manager_version" \
-  --upstream-manifest-version "$upstream_manifest_version" \
-  --fallback-manifest "$manifest_template"
-
-if [ -n "$additional_validator" ]; then
-  [ -f "$additional_validator" ] || \
-    spw_die "additional plugin validator not found: $additional_validator"
-  if ! python3 "$additional_validator" "$tmp_plugin"; then
-    spw_die "additional plugin validation failed"
-  fi
-fi
-
-spw_replace_generated_tree "$tmp_plugin" "$plugin_root"
-
-echo "prepared $resolved_ref at $commit"

package/scripts/probe

@@ -1,61 +0,0 @@
-#!/bin/sh
-set -eu
-
-root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
-. "$root/scripts/core/common.sh"
-. "$root/scripts/core/upstream.sh"
-. "$root/scripts/core/provenance.sh"
-. "$root/scripts/core/status.sh"
-. "$root/scripts/core/lifecycle.sh"
-. "$root/scripts/core/adapter.sh"
-
-upstream_url="${SUPERPOWERS_UPSTREAM_URL:-$SPW_UPSTREAM_URL_DEFAULT}"
-requested_ref=$(spw_config_ref "$root")
-resolved_record=$(spw_resolve_ref "$upstream_url" "$requested_ref")
-resolved_ref=$(printf '%s\n' "$resolved_record" | awk '{ print $2 }')
-desired_commit=$(printf '%s\n' "$resolved_record" | awk '{ print $3 }')
-
-generated_commit=$(spw_generated_commit_or_empty "$root")
-tmp_parent="${TMPDIR:-/tmp}"
-if ! probe_workspace=$(mktemp -d "$tmp_parent/superpowers-manager.probe.XXXXXX"); then
-  spw_die "cannot create probe workspace under $tmp_parent"
-fi
-fingerprint_result="$probe_workspace/fingerprint.json"
-ownership_result="$probe_workspace/ownership.json"
-cleanup() {
-  status=$?
-  trap - 0 HUP INT TERM
-  rm -rf "$probe_workspace" || :
-  exit "$status"
-}
-trap cleanup 0
-trap 'exit 129' HUP
-trap 'exit 130' INT
-trap 'exit 143' TERM
-
-TMPDIR="$probe_workspace"
-export TMPDIR
-spw_inspect_fingerprint "$fingerprint_result"
-installed_commit=$(spw_adapter_result_get "$fingerprint_result" "fingerprint")
-spw_inspect_ownership "$ownership_result"
-identity_state=$(spw_adapter_result_get "$ownership_result" "identity_state")
-
-status=$(spw_status_for_commits "$desired_commit" "$generated_commit" "$installed_commit")
-
-if [ "${1:-}" = "--porcelain" ]; then
-  printf 'requested_ref=%s\n' "$requested_ref"
-  printf 'resolved_ref=%s\n' "$resolved_ref"
-  printf 'desired_commit=%s\n' "$desired_commit"
-  printf 'generated_commit=%s\n' "$generated_commit"
-  printf 'installed_commit=%s\n' "$installed_commit"
-  printf 'identity_state=%s\n' "$identity_state"
-  printf 'status=%s\n' "$status"
-else
-  printf 'requested ref: %s\n' "$requested_ref"
-  printf 'resolved ref: %s\n' "$resolved_ref"
-  printf 'desired commit: %s\n' "$desired_commit"
-  printf 'generated plugin commit: %s\n' "${generated_commit:-not present}"
-  printf 'installed manager commit or fingerprint: %s\n' "${installed_commit:-not detected}"
-  printf 'Codex identity state: %s\n' "$identity_state"
-  printf 'status: %s\n' "$status"
-fi

package/scripts/uninstall

@@ -1,44 +0,0 @@
-#!/bin/sh
-set -eu
-
-root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
-. "$root/scripts/core/common.sh"
-. "$root/scripts/core/provenance.sh"
-. "$root/scripts/core/lifecycle.sh"
-. "$root/scripts/core/adapter.sh"
-
-spw_require_command python3
-
-tmp_parent="${TMPDIR:-/tmp}"
-if ! uninstall_workspace=$(mktemp -d "$tmp_parent/superpowers-manager.uninstall.XXXXXX"); then
-  spw_die "cannot create uninstall workspace under $tmp_parent"
-fi
-inspect_result="$uninstall_workspace/inspect.json"
-uninstall_result="$uninstall_workspace/uninstall.json"
-cleanup() {
-  status=$?
-  trap - 0 HUP INT TERM
-  rm -rf "$uninstall_workspace" || :
-  exit "$status"
-}
-trap cleanup 0
-trap 'exit 129' HUP
-trap 'exit 130' INT
-trap 'exit 143' TERM
-
-TMPDIR="$uninstall_workspace"
-export TMPDIR
-
-spw_inspect_ownership "$inspect_result"
-plugin_present=$(spw_adapter_result_boolean "$inspect_result" "resources.plugin")
-marketplace_present=$(spw_adapter_result_boolean "$inspect_result" "resources.marketplace")
-
-spw_adapter_uninstall "$uninstall_result" "$plugin_present" "$marketplace_present"
-
-spw_inspect_ownership "$inspect_result"
-spw_verify_uninstalled_resources "$inspect_result"
-identity_state=$(spw_adapter_result_get "$inspect_result" "identity_state")
-spw_report_legacy_state "$identity_state"
-
-echo "uninstall complete"
-echo "note: local generated artifacts under plugins/superpowers/ and .cache/upstream/ were left in place; remove them manually or regenerate with scripts/prepare."

package/scripts/update

@@ -1,31 +0,0 @@
-#!/bin/sh
-set -eu
-
-root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
-. "$root/scripts/core/common.sh"
-. "$root/scripts/core/lifecycle.sh"
-
-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 adapter identity state"
-spw_require_no_legacy_state "$identity_state"
-status=$(printf '%s\n' "$probe_output" | awk -F= '$1 == "status" { print $2 }')
-
-case "$status" in
-  current)
-    printf '%s\n' "$probe_output"
-    echo "manager is current"
-    ;;
-  needs\ prepare)
-    sh "$root/scripts/prepare"
-    sh "$root/scripts/install"
-    ;;
-  needs\ install)
-    sh "$root/scripts/install"
-    ;;
-  *)
-    echo "$probe_output"
-    echo "error: unknown probe status: $status" >&2
-    exit 1
-    ;;
-esac