superpowers-manager 0.1.4 → 0.1.6

package/scripts/adapters/codex/lib.sh

@@ -0,0 +1,391 @@
+#!/bin/sh
+# Sourced module; callers own set -eu.
+
+SPW_PLUGIN_ID="superpowers@superpowers-manager"
+SPW_MARKETPLACE_NAME="superpowers-manager"
+SPW_LEGACY_PLUGIN_ID="superpowers@superpowers-wrapper"
+SPW_LEGACY_MARKETPLACE_NAME="superpowers-wrapper"
+
+# Given a JSON document as the FIRST ARGUMENT (a string), print "present" if any
+# element of the top-level array <array_key> is an object whose <field> equals
+# <value>, else print "absent" (exit 0). On unparseable JSON or invalid schema,
+# print nothing and exit 2 so callers can fail closed rather than treat an
+# unreadable listing as "absent". Every item in the inspected array must be an
+# object with a non-empty string <field>; otherwise ownership is unprovable and
+# the helper exits 2 instead of treating the malformed entry as unrelated.
+# The JSON is passed as an argument (exactly as spw_json_get takes a file path),
+# NOT on stdin: the here-doc below is Python's stdin (its program source), so a
+# json.load(sys.stdin) here would read the program, not the caller's JSON.
+spw_json_array_has() {
+  json="$1"
+  array_key="$2"
+  field="$3"
+  value="$4"
+  python3 - "$json" "$array_key" "$field" "$value" <<'PY'
+import json, sys
+raw, array_key, field, value = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4]
+try:
+    data = json.loads(raw)
+except (json.JSONDecodeError, RecursionError):
+    sys.exit(2)
+if not isinstance(data, dict):
+    sys.exit(2)
+items = data.get(array_key)
+if not isinstance(items, list):
+    sys.exit(2)
+for item in items:
+    if not isinstance(item, dict):
+        sys.exit(2)
+    field_value = item.get(field)
+    if not isinstance(field_value, str) or not field_value:
+        sys.exit(2)
+found = any(item[field] == value for item in items)
+print("present" if found else "absent")
+PY
+}
+
+# Print the registered root of <marketplace_name> from a marketplace-list JSON
+# document (as a string argument, like spw_json_array_has), or nothing if the
+# marketplace is absent. Exit 2 on unparseable JSON, a non-object item, or an
+# item without a non-empty string name: such an item cannot be proven unrelated
+# and must not be mistaken for an absent manager marketplace. Validate root only
+# on the matching item; unrelated marketplace roots are never read. A matching
+# item without a non-empty string root also exits 2. Empty output is unambiguous:
+# a valid registered root is always a non-empty path.
+spw_marketplace_root_from_json() {
+  json="$1"
+  marketplace_name="$2"
+  python3 - "$json" "$marketplace_name" <<'PY'
+import json, sys
+raw, name = sys.argv[1], sys.argv[2]
+try:
+    data = json.loads(raw)
+except (json.JSONDecodeError, RecursionError):
+    sys.exit(2)
+if not isinstance(data, dict):
+    sys.exit(2)
+items = data.get("marketplaces")
+if not isinstance(items, list):
+    sys.exit(2)
+for item in items:
+    if not isinstance(item, dict):
+        sys.exit(2)
+    item_name = item.get("name")
+    if not isinstance(item_name, str) or not item_name:
+        sys.exit(2)
+for item in items:
+    if item["name"] == name:
+        item_root = item.get("root")
+        if not isinstance(item_root, str) or not item_root:
+            sys.exit(2)
+        print(item_root)
+        sys.exit(0)
+PY
+}
+
+# Print "same" if the two paths refer to the same physical location, else
+# "different". Physical-path normalization via os.path.realpath on both
+# sides (handles /var vs /private/var and other symlinked roots); if
+# realpath fails, fall back to comparing the original strings.
+spw_paths_equal() {
+  python3 - "$1" "$2" <<'PY'
+import os, sys
+a, b = sys.argv[1], sys.argv[2]
+try:
+    na, nb = os.path.realpath(a), os.path.realpath(b)
+except OSError:
+    na, nb = a, b
+print("same" if na == nb else "different")
+PY
+}
+
+spw_find_installed_metadata() {
+  search_root="${SUPERPOWERS_INSTALLED_SEARCH_ROOT:-$HOME/.codex}"
+  find "$search_root" \
+    \( -path "*/$SPW_MARKETPLACE_NAME/superpowers/.superpowers-upstream.json" \
+       -o -path "*/$SPW_MARKETPLACE_NAME/superpowers/*/.superpowers-upstream.json" \) \
+    -type f 2>/dev/null | head -n 1
+}
+
+spw_find_installed_manifest() {
+  search_root="${SUPERPOWERS_INSTALLED_SEARCH_ROOT:-$HOME/.codex}"
+  find "$search_root" \
+    \( -path "*/$SPW_MARKETPLACE_NAME/superpowers/.codex-plugin/plugin.json" \
+       -o -path "*/$SPW_MARKETPLACE_NAME/superpowers/*/.codex-plugin/plugin.json" \) \
+    -type f 2>/dev/null | head -n 1
+}
+
+spw_codex_json_get_or_empty() {
+  file="$1"
+  key="$2"
+  [ -f "$file" ] || return 1
+  python3 - "$file" "$key" <<'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 handle:
+        data = json.load(handle, parse_constant=reject_constant)
+except (OSError, UnicodeError, json.JSONDecodeError, RecursionError, ValueError):
+    sys.exit(1)
+
+if nesting_exceeds_limit(data) or not isinstance(data, dict):
+    sys.exit(1)
+
+value = data
+for part in dotted_key.split("."):
+    if not isinstance(value, dict):
+        value = ""
+        break
+    value = value.get(part, "")
+
+if value is None:
+    value = ""
+if not isinstance(value, str):
+    sys.exit(1)
+print(value)
+PY
+}
+
+spw_codex_metadata_commit_or_empty() {
+  file="$1"
+  if ! commit=$(spw_codex_json_get_or_empty "$file" "commit"); then
+    return 1
+  fi
+  case "$commit" in
+    ""|*[!0-9a-fA-F]*) return 1 ;;
+  esac
+  case "${#commit}" in
+    7|40) printf '%s\n' "$commit" ;;
+    *) return 1 ;;
+  esac
+}
+
+spw_apply_manifest_overlay() {
+  manifest="$1"
+  version="$2"
+  python3 - "$manifest" "$version" <<'PY'
+import json
+import sys
+
+path, version = 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 manifest JSON in {path}: "
+        f"line {exc.lineno} column {exc.colno}: {exc.msg}"
+    )
+except (OSError, UnicodeError) as exc:
+    sys.exit(f"cannot read manifest JSON in {path}: {exc}")
+except ValueError as exc:
+    sys.exit(f"invalid manifest 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"manifest must be a JSON object: {path}")
+
+data["version"] = version
+data["skills"] = "./skills/"
+data.pop("hooks", None)
+
+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"manifest JSON nesting exceeds limit while writing {path}: {exc}")
+except (OSError, UnicodeError, ValueError) as exc:
+    sys.exit(f"cannot write manifest JSON in {path}: {exc}")
+PY
+}
+
+spw_manifest_short_sha_or_empty() {
+  file="$1"
+  if ! version=$(spw_codex_json_get_or_empty "$file" "version"); then
+    return 1
+  fi
+  case "$version" in
+    *+manager.*)
+      short="${version##*.}"
+      case "$short" in
+        [0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F])
+          printf '%s\n' "$short"
+          ;;
+      esac
+      ;;
+  esac
+}
+
+spw_installed_commit_or_empty() {
+  installed_metadata=$(spw_find_installed_metadata || true)
+  installed_manifest=$(spw_find_installed_manifest || true)
+  installed_commit=""
+  if [ -n "$installed_metadata" ]; then
+    installed_commit=$(spw_codex_metadata_commit_or_empty "$installed_metadata" || true)
+  fi
+  if [ -z "$installed_commit" ] && [ -n "$installed_manifest" ]; then
+    installed_commit=$(spw_manifest_short_sha_or_empty "$installed_manifest" || true)
+  fi
+  printf '%s\n' "$installed_commit"
+}
+
+spw_codex_emit() {
+  operation="$1"
+  ok="$2"
+  result_json="$3"
+  code="$4"
+  error_message="$5"
+  hints_file="$6"
+  messages_file="$7"
+  python3 - "$operation" "$ok" "$result_json" "$code" "$error_message" "$hints_file" "$messages_file" <<'PY'
+import json
+import sys
+
+operation, ok_text, result_text, code, error_message, hints_path, messages_path = sys.argv[1:]
+
+def has_terminal_control(value):
+    return any(
+        ord(char) < 0x20
+        or 0x7f <= ord(char) <= 0x9f
+        or 0xd800 <= ord(char) <= 0xdfff
+        for char in value
+    )
+
+if any(has_terminal_control(value) for value in (operation, code, error_message)):
+    raise SystemExit("protocol strings must not contain terminal control characters")
+
+messages = []
+if messages_path:
+    with open(messages_path, encoding="utf-8") as handle:
+        for number, raw in enumerate(handle, 1):
+            line = raw.rstrip("\n")
+            if "\t" not in line:
+                raise SystemExit(f"invalid message record at line {number}")
+            channel, text = line.split("\t", 1)
+            if (
+                channel not in {"stdout", "stderr"}
+                or not text
+                or "\t" in text
+                or "\r" in text
+                or has_terminal_control(text)
+            ):
+                raise SystemExit(f"invalid message record at line {number}")
+            messages.append({"channel": channel, "text": text})
+
+ok = ok_text == "true"
+if ok:
+    envelope = {
+        "protocol": 1,
+        "operation": operation,
+        "ok": True,
+        "messages": messages,
+        "result": json.loads(result_text),
+        "error": None,
+    }
+else:
+    hints = []
+    if hints_path:
+        with open(hints_path, encoding="utf-8") as handle:
+            hints = [line.rstrip("\n") for line in handle if line.rstrip("\n")]
+    if any(has_terminal_control(hint) for hint in hints):
+        raise SystemExit("protocol hints must not contain terminal control characters")
+    envelope = {
+        "protocol": 1,
+        "operation": operation,
+        "ok": False,
+        "messages": messages,
+        "result": None,
+        "error": {"code": code, "message": error_message, "hints": hints},
+    }
+json.dump(envelope, sys.stdout, allow_nan=False, separators=(",", ":"))
+sys.stdout.write("\n")
+PY
+}
+
+spw_codex_success() {
+  spw_codex_emit "$1" true "$2" "" "" "" "$3"
+}
+
+spw_codex_failure() {
+  spw_codex_emit "$1" false '{}' "$2" "$3" "$4" "$5"
+  exit 1
+}
+
+# Append command output as structured message records while keeping the
+# tab-delimited spool format unambiguous. Each physical command-output line is
+# escaped with Python's unicode_escape codec so literal backslashes remain
+# distinguishable from rendered control characters like \t and \r.
+spw_codex_append_messages() {
+  messages_file="$1"
+  channel="$2"
+  input_file="$3"
+  [ -f "$input_file" ] || return 0
+  python3 - "$messages_file" "$channel" "$input_file" <<'PY'
+from pathlib import Path
+import sys
+
+messages_path = Path(sys.argv[1])
+channel = sys.argv[2]
+input_path = Path(sys.argv[3])
+
+chunks = input_path.read_bytes().split(b"\n")
+with messages_path.open("a", encoding="utf-8") as handle:
+    for chunk in chunks:
+        if not chunk:
+            continue
+        text = chunk.decode("utf-8", errors="backslashreplace")
+        escaped = text.encode("unicode_escape").decode("ascii")
+        if not escaped:
+            continue
+        handle.write(f"{channel}\t{escaped}\n")
+PY
+}

package/scripts/{validate-generated-plugin.py → adapters/codex/validate-generated-plugin.py}

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Validate the wrapper-owned generated Superpowers plugin contract."""
+"""Validate the manager-owned generated Superpowers plugin contract."""
 
 from __future__ import annotations
 
@@ -53,7 +53,7 @@ def json_nesting_exceeds_limit(value: Any) -> bool:
 
 def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
     parser = argparse.ArgumentParser(
-        description="Validate a generated Superpowers wrapper candidate."
+        description="Validate a generated Superpowers manager candidate."
     )
     parser.add_argument("--plugin-root", required=True)
     parser.add_argument("--source", required=True)
@@ -270,7 +270,7 @@ def validate_provenance(args: argparse.Namespace, plugin_root: Path, errors: lis
     if provenance is None:
         return
     if set(provenance) != PROVENANCE_KEYS:
-        errors.append("provenance keys do not match the wrapper-owned contract")
+        errors.append("provenance keys do not match the manager-owned contract")
     expected = {
         "source": args.source,
         "requested_ref": args.requested_ref,

package/scripts/core/adapter.sh

@@ -0,0 +1,92 @@
+#!/bin/sh
+# Sourced module; callers own set -eu.
+
+spw_adapter_package_root() {
+  if [ -n "${SPW_PACKAGE_ROOT:-}" ]; then
+    printf '%s\n' "$SPW_PACKAGE_ROOT"
+  elif [ -n "${root:-}" ]; then
+    printf '%s\n' "$root"
+  else
+    spw_root
+  fi
+}
+
+SPW_ADAPTER_ROOT=$(spw_adapter_package_root)
+SPW_ADAPTER="${SPW_ADAPTER:-$SPW_ADAPTER_ROOT/scripts/adapters/codex/adapter}"
+SPW_ADAPTER_RESPONSE_VALIDATOR="${SPW_ADAPTER_RESPONSE_VALIDATOR:-$SPW_ADAPTER_ROOT/scripts/core/validate-adapter-response.py}"
+
+spw_invoke_adapter() {
+  operation="$1"
+  result_file="$2"
+  inspect_view="$3"
+  shift 3
+  [ "${1:-}" = "--" ] || spw_die "internal adapter invocation missing --"
+  shift
+
+  response_file="${result_file}.response"
+  adapter_exit=0
+  "$SPW_ADAPTER" "$operation" "$@" > "$response_file" || adapter_exit=$?
+
+  args=""
+  if [ -n "$inspect_view" ]; then
+    args="$inspect_view"
+  fi
+  if [ -n "$args" ]; then
+    python3 -S "$SPW_ADAPTER_RESPONSE_VALIDATOR" \
+      --operation "$operation" --adapter-exit "$adapter_exit" \
+      --response "$response_file" --result "$result_file" \
+      --inspect-view "$inspect_view"
+  else
+    python3 -S "$SPW_ADAPTER_RESPONSE_VALIDATOR" \
+      --operation "$operation" --adapter-exit "$adapter_exit" \
+      --response "$response_file" --result "$result_file"
+  fi
+}
+
+spw_adapter_result_get() {
+  result_file="$1"
+  dotted_key="$2"
+  spw_json_get "$result_file" "$dotted_key"
+}
+
+spw_adapter_result_boolean() {
+  result_file="$1"
+  dotted_key="$2"
+  value=$(spw_adapter_result_get "$result_file" "$dotted_key")
+  case "$value" in
+    true|True)
+      printf 'true\n'
+      ;;
+    false|False)
+      printf 'false\n'
+      ;;
+    *)
+      spw_die "expected Boolean adapter result at $dotted_key in $result_file"
+      ;;
+  esac
+}
+
+spw_inspect_fingerprint() {
+  result_file="$1"
+  spw_invoke_adapter inspect "$result_file" fingerprint -- --view fingerprint
+}
+
+spw_inspect_ownership() {
+  result_file="$1"
+  spw_invoke_adapter inspect "$result_file" ownership -- --view ownership
+}
+
+spw_adapter_install() {
+  result_file="$1"
+  package_root="$2"
+  spw_invoke_adapter install "$result_file" "" -- --package-root "$package_root"
+}
+
+spw_adapter_uninstall() {
+  result_file="$1"
+  plugin_present="$2"
+  marketplace_present="$3"
+  spw_invoke_adapter uninstall "$result_file" "" -- \
+    --plugin-present "$plugin_present" \
+    --marketplace-present "$marketplace_present"
+}

package/scripts/core/common.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+# Sourced module; callers own set -eu.
+
+spw_die() {
+  echo "error: $*" >&2
+  exit 1
+}
+
+spw_require_command() {
+  command_name="$1"
+  if ! command -v "$command_name" >/dev/null 2>&1; then
+    spw_die "required command not found: $command_name"
+  fi
+}
+
+spw_root() {
+  CDPATH= cd -- "$(dirname "$0")/.." && pwd
+}
+
+spw_copy_path_if_present() {
+  src="$1"
+  dst="$2"
+  if [ -e "$src" ]; then
+    rm -rf "$dst"
+    cp -R "$src" "$dst"
+  fi
+}
+
+spw_require_upstream_path() {
+  path="$1"
+  label="$2"
+  if [ ! -e "$path" ]; then
+    spw_die "required upstream path missing: $label"
+  fi
+}

package/scripts/core/lifecycle.sh

@@ -0,0 +1,127 @@
+#!/bin/sh
+# Sourced module; callers own set -eu.
+
+# Replace the live tree with a single atomic rename, keeping a backup so a
+# failed swap restores the previous working generated tree. candidate and
+# live_root must be same-filesystem siblings for atomic renames.
+spw_replace_generated_tree() {
+  candidate="$1"
+  live_root="$2"
+  parent=$(dirname "$live_root")
+  backup="$parent/.superpowers.bak.$$"
+
+  rm -rf "$backup"
+  if [ -e "$live_root" ]; then
+    mv "$live_root" "$backup"
+  fi
+  if mv "$candidate" "$live_root"; then
+    rm -rf "$backup"
+  else
+    if [ -e "$backup" ]; then
+      mv "$backup" "$live_root"
+    fi
+    rm -rf "$candidate"
+    spw_die "failed to install generated tree into $live_root; previous tree restored"
+  fi
+}
+
+spw_generated_metadata_path() (
+  generated_root="$1"
+  printf '%s\n' "$generated_root/plugins/superpowers/.superpowers-upstream.json"
+)
+
+spw_generated_commit_or_empty() (
+  generated_root="$1"
+  generated_metadata=$(spw_generated_metadata_path "$generated_root")
+  spw_metadata_commit_lenient_or_empty "$generated_metadata"
+)
+
+spw_require_no_legacy_state() {
+  identity_state="$1"
+  case "$identity_state" in
+    neither|manager)
+      return 0
+      ;;
+    legacy|both)
+      printf '%s\n' \
+        'Legacy superpowers-wrapper Codex state is installed.' \
+        'Run: npx superpowers-wrapper@0.1.1 uninstall' \
+        'Then run: npx superpowers-manager install' >&2
+      return 1
+      ;;
+    *)
+      spw_die "unknown adapter identity state: $identity_state"
+      ;;
+  esac
+}
+
+spw_report_legacy_state() {
+  case "$1" in
+    legacy|both)
+      printf '%s\n' \
+        'Legacy superpowers-wrapper Codex state remains installed.' \
+        'Run: npx superpowers-wrapper@0.1.1 uninstall'
+      ;;
+    neither|manager)
+      ;;
+    *)
+      spw_die "unknown adapter identity state: $1"
+      ;;
+  esac
+}
+
+spw_verify_installed_fingerprint() {
+  desired_commit="$1"
+  install_result="$2"
+  inspect_result="$3"
+  if ! spw_inspect_fingerprint "$inspect_result"; then
+    echo "error: installed manager fingerprint inspection failed after install." >&2
+    return 1
+  fi
+  if ! installed_commit=$(spw_adapter_result_get "$inspect_result" "fingerprint"); then
+    echo "error: cannot parse installed manager fingerprint inspection result after install." >&2
+    return 1
+  fi
+  printf 'desired_commit=%s\n' "$desired_commit"
+  printf 'installed_commit=%s\n' "$installed_commit"
+  if [ -n "$installed_commit" ] && spw_commit_matches "$desired_commit" "$installed_commit"; then
+    echo "manager updated"
+    return 0
+  fi
+
+  hint=""
+  if [ -f "$install_result" ]; then
+    if [ -n "$installed_commit" ]; then
+      hint=$(spw_adapter_result_get "$install_result" "verification_hints.mismatch" || true)
+    else
+      hint=$(spw_adapter_result_get "$install_result" "verification_hints.missing" || true)
+    fi
+  fi
+
+  if [ -n "$installed_commit" ]; then
+    echo "error: installed manager fingerprint does not match the prepared plugin after install." >&2
+  else
+    echo "error: installed manager fingerprint is not detectable after install." >&2
+  fi
+  if [ -n "$hint" ]; then
+    echo "hint: $hint" >&2
+  fi
+  return 1
+}
+
+spw_verify_uninstalled_resources() {
+  inspect_result="$1"
+
+  if ! plugin_present=$(spw_adapter_result_boolean "$inspect_result" "resources.plugin"); then
+    return 1
+  fi
+  if ! marketplace_present=$(spw_adapter_result_boolean "$inspect_result" "resources.marketplace"); then
+    return 1
+  fi
+  if [ "$plugin_present" = true ]; then
+    spw_die "owned plugin resource is still installed after removal"
+  fi
+  if [ "$marketplace_present" = true ]; then
+    spw_die "owned marketplace resource is still registered after removal"
+  fi
+}