superpowers-manager 0.1.4 → 0.1.6

package/scripts/core/provenance.sh

@@ -0,0 +1,135 @@
+#!/bin/sh
+# Sourced module; callers own set -eu.
+
+spw_json_get() {
+  file="$1"
+  key="$2"
+  if ! value=$(
+    python3 - "$file" "$key" 2>&1 <<'PY'
+import json
+import sys
+
+path, dotted_key = sys.argv[1:]
+MAX_JSON_NESTING = 256
+
+def reject_constant(constant):
+    raise ValueError(f"non-standard numeric constant: {constant}")
+
+def nesting_exceeds_limit(value):
+    stack = [(value, 0)]
+    while stack:
+        current, depth = stack.pop()
+        if isinstance(current, dict):
+            next_depth = depth + 1
+            if next_depth > MAX_JSON_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_JSON_NESTING:
+                return True
+            stack.extend((child, next_depth) for child in current)
+    return False
+
+try:
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f, parse_constant=reject_constant)
+except RecursionError:
+    sys.exit(f"JSON nesting exceeds limit in {path}")
+except json.JSONDecodeError as exc:
+    sys.exit(
+        f"invalid JSON in {path}: "
+        f"line {exc.lineno} column {exc.colno}: {exc.msg}"
+    )
+except (OSError, UnicodeError) as exc:
+    sys.exit(f"cannot read JSON in {path}: {exc}")
+except ValueError as exc:
+    sys.exit(f"invalid JSON in {path}: {exc}")
+
+if nesting_exceeds_limit(data):
+    sys.exit(f"JSON nesting exceeds limit in {path}")
+
+if not isinstance(data, dict):
+    sys.exit(f"JSON value must be an object in {path}")
+
+value = data
+for part in dotted_key.split("."):
+    if not isinstance(value, dict):
+        value = ""
+        break
+    value = value.get(part, "")
+try:
+    print(value if value is not None else "")
+except (OSError, UnicodeError) as exc:
+    sys.exit(f"cannot output JSON value from {path}: {exc}")
+PY
+  ); then
+    spw_die "$value"
+  fi
+  printf '%s\n' "$value"
+}
+
+spw_write_metadata_json() {
+  file="$1"
+  source="$2"
+  requested_ref="$3"
+  resolved_ref="$4"
+  commit="$5"
+  upstream_manifest_version="$6"
+  python3 - "$file" "$source" "$requested_ref" "$resolved_ref" "$commit" "$upstream_manifest_version" <<'PY'
+import json, sys
+path, source, requested, resolved, commit, version = sys.argv[1:]
+data = {
+    "source": source,
+    "requested_ref": requested,
+    "resolved_ref": resolved,
+    "commit": commit,
+    "upstream_manifest_version": version,
+}
+try:
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, allow_nan=False)
+        f.write("\n")
+except RecursionError as exc:
+    sys.exit(f"JSON nesting exceeds limit while writing {path}: {exc}")
+except (OSError, UnicodeError, ValueError) as exc:
+    sys.exit(f"cannot write JSON to {path}: {exc}")
+PY
+}
+
+spw_metadata_commit_or_empty() {
+  file="$1"
+  if [ -f "$file" ]; then
+    spw_json_get "$file" "commit"
+  fi
+}
+
+spw_metadata_commit_lenient_or_empty() {
+  file="$1"
+  [ -f "$file" ] || return 0
+
+  if value=$(
+    python3 -S - "$file" 2>/dev/null <<'PY'
+import json
+import re
+import sys
+
+path = sys.argv[1]
+
+def reject_constant(constant):
+    raise ValueError(f"non-standard numeric constant: {constant}")
+
+try:
+    with open(path, "r", encoding="utf-8") as handle:
+        data = json.load(handle, parse_constant=reject_constant)
+except (OSError, UnicodeError, ValueError, RecursionError):
+    raise SystemExit(1)
+
+commit = data.get("commit") if isinstance(data, dict) else None
+if isinstance(commit, str) and re.fullmatch(r"[0-9a-fA-F]{40}", commit):
+    print(commit)
+PY
+  ); then
+    printf '%s\n' "$value"
+  fi
+}

package/scripts/core/status.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+# Sourced module; callers own set -eu.
+
+spw_commit_matches() {
+  desired="$1"
+  observed="$2"
+  short=$(printf '%s' "$desired" | cut -c 1-7)
+  [ -n "$observed" ] && { [ "$observed" = "$desired" ] || [ "$observed" = "$short" ]; }
+}
+
+spw_status_for_commits() {
+  desired="$1"
+  generated="$2"
+  installed="$3"
+
+  if [ -z "$generated" ]; then
+    printf '%s\n' "needs prepare"
+  elif ! spw_commit_matches "$desired" "$generated"; then
+    printf '%s\n' "needs prepare"
+  elif [ -z "$installed" ]; then
+    printf '%s\n' "needs install"
+  elif ! spw_commit_matches "$desired" "$installed"; then
+    printf '%s\n' "needs install"
+  else
+    printf '%s\n' "current"
+  fi
+}

package/scripts/core/upstream.sh

@@ -0,0 +1,146 @@
+#!/bin/sh
+# Sourced module; callers own set -eu.
+
+SPW_UPSTREAM_URL_DEFAULT="https://github.com/obra/superpowers"
+
+spw_config_ref() (
+  config_root="$1"
+  if [ -n "${SUPERPOWERS_REF:-}" ]; then
+    printf '%s\n' "$SUPERPOWERS_REF"
+    return
+  fi
+  sed -n '1{s/[[:space:]]*$//;p;}' "$config_root/config/upstream-ref"
+)
+
+spw_short_commit() {
+  commit="$1"
+  printf '%s' "$commit" | cut -c 1-7
+}
+
+spw_is_semver_base() {
+  version="$1"
+  printf '%s' "$version" | grep -Eq '^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?$'
+}
+
+spw_sanitize_ref_for_version() {
+  ref="$1"
+  sanitized=$(printf '%s' "$ref" | sed 's/[^0-9A-Za-z-][^0-9A-Za-z-]*/-/g; s/^-*//; s/-*$//')
+  sanitized=$(printf '%s' "$sanitized" | cut -c 1-48 | sed 's/^-*//; s/-*$//')
+  if [ -z "$sanitized" ]; then
+    sanitized="unknown"
+  fi
+  printf '%s' "$sanitized"
+}
+
+spw_manifest_version_for_ref() {
+  requested_ref="$1"
+  resolution_kind="$2"
+  resolved_ref="$3"
+  commit="$4"
+  short=$(spw_short_commit "$commit")
+
+  case "$resolution_kind" in
+    latest-release|tag)
+      base=$(printf '%s' "$resolved_ref" | sed -n 's/^v//p')
+      if [ -n "$base" ] && spw_is_semver_base "$base"; then
+        printf '%s+manager.%s\n' "$base" "$short"
+        return
+      fi
+      ;;
+    ref)
+      if [ "$requested_ref" = "main" ]; then
+        printf '0.0.0-main+manager.%s\n' "$short"
+        return
+      fi
+      sanitized=$(spw_sanitize_ref_for_version "$requested_ref")
+      printf '0.0.0-ref-%s+manager.%s\n' "$sanitized" "$short"
+      return
+      ;;
+    raw-commit)
+      ;;
+  esac
+
+  printf '0.0.0+manager.%s\n' "$short"
+}
+
+spw_manifest_version_for_commit() {
+  commit="$1"
+  spw_manifest_version_for_ref "$commit" "raw-commit" "$commit" "$commit"
+}
+
+spw_select_latest_release_from_ls_remote() {
+  awk '
+    $2 ~ /^refs\/tags\/v[0-9]+\.[0-9]+\.[0-9]+(\^\{\})?$/ {
+      ref = $2
+      peeled = 0
+      if (ref ~ /\^\{\}$/) {
+        peeled = 1
+        sub(/\^\{\}$/, "", ref)
+      }
+      tag = ref
+      sub(/^refs\/tags\//, "", tag)
+      split(substr(tag, 2), parts, ".")
+      key = sprintf("%010d.%010d.%010d", parts[1], parts[2], parts[3])
+      tag_by_key[key] = tag
+      if (peeled || !(tag in sha_by_tag)) {
+        sha_by_tag[tag] = $1
+      }
+    }
+    END {
+      for (key in tag_by_key) {
+        tag = tag_by_key[key]
+        print key, tag, sha_by_tag[tag]
+      }
+    }
+  ' | sort | tail -n 1 | awk '
+    NF == 3 { print $2 " " $3; found = 1 }
+    END { if (!found) exit 1 }
+  '
+}
+
+spw_resolve_ref() {
+  upstream_url="$1"
+  requested_ref="$2"
+  spw_require_command git
+
+  if [ "$requested_ref" = "latest-release" ]; then
+    if ! output=$(git ls-remote --tags "$upstream_url" 'refs/tags/v*' 2>&1); then
+      spw_die "cannot query upstream tags from $upstream_url: $output"
+    fi
+    if ! selected=$(printf '%s\n' "$output" | spw_select_latest_release_from_ls_remote); then
+      spw_die "no stable semver tag found for latest-release"
+    fi
+    printf 'latest-release %s\n' "$selected"
+    return
+  fi
+
+  if printf '%s' "$requested_ref" | grep -Eq '^[0-9a-fA-F]{40}$'; then
+    printf 'raw-commit %s %s\n' "$requested_ref" "$requested_ref"
+    return
+  fi
+
+  if ! tag_output=$(git ls-remote --tags "$upstream_url" "refs/tags/$requested_ref" "refs/tags/$requested_ref^{}" 2>&1); then
+    spw_die "cannot query upstream tag $requested_ref from $upstream_url: $tag_output"
+  fi
+  resolved=$(printf '%s\n' "$tag_output" | awk -v tag_ref="refs/tags/$requested_ref" '
+    NF >= 2 && ($2 == tag_ref || $2 == tag_ref "^{}") {
+      sha = $1
+    }
+    END { if (sha != "") print sha }
+  ')
+  if [ -n "$resolved" ]; then
+    printf 'tag %s %s\n' "$requested_ref" "$resolved"
+    return
+  fi
+
+  if ! ref_output=$(git ls-remote "$upstream_url" "$requested_ref" 2>&1); then
+    spw_die "cannot query upstream ref $requested_ref from $upstream_url: $ref_output"
+  fi
+  resolved=$(printf '%s\n' "$ref_output" | awk 'NF >= 2 { print $1; exit }')
+  if [ -n "$resolved" ]; then
+    printf 'ref %s %s\n' "$requested_ref" "$resolved"
+    return
+  fi
+
+  spw_die "cannot resolve upstream ref: $requested_ref"
+}

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

@@ -0,0 +1,245 @@
+#!/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

@@ -2,27 +2,22 @@
 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"
+[ -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
@@ -40,19 +35,26 @@ 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=$(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
-
-spw_verify_refresh "$desired_commit"