superpowers-manager 0.1.4 → 0.2.0

package/scripts/adapters/codex/lib.sh

@@ -0,0 +1,449 @@
+#!/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_active_plugin_version_from_json() {
+  json="$1"
+  plugin_id="$2"
+  python3 - "$json" "$plugin_id" <<'PY'
+import json
+import sys
+
+raw, plugin_id = sys.argv[1:]
+
+def reject_constant(value):
+    raise ValueError(f"non-standard JSON constant: {value}")
+
+def has_terminal_control(value):
+    return any(
+        ord(character) < 0x20
+        or 0x7F <= ord(character) <= 0x9F
+        or 0xD800 <= ord(character) <= 0xDFFF
+        for character in value
+    )
+
+try:
+    data = json.loads(raw, parse_constant=reject_constant)
+except (json.JSONDecodeError, RecursionError, ValueError):
+    sys.exit(2)
+
+if not isinstance(data, dict):
+    sys.exit(2)
+items = data.get("installed")
+if not isinstance(items, list):
+    sys.exit(2)
+
+matches = []
+for item in items:
+    if not isinstance(item, dict):
+        sys.exit(2)
+    item_plugin_id = item.get("pluginId")
+    if not isinstance(item_plugin_id, str) or not item_plugin_id:
+        sys.exit(2)
+    if item_plugin_id == plugin_id:
+        matches.append(item)
+
+if len(matches) > 1:
+    sys.exit(2)
+if not matches:
+    sys.exit(0)
+
+version = matches[0].get("version")
+if (
+    not isinstance(version, str)
+    or not version
+    or version in {".", ".."}
+    or "/" in version
+    or "\\" in version
+    or has_terminal_control(version)
+):
+    sys.exit(2)
+print(version)
+PY
+}
+
+spw_installed_root_for_version() {
+  search_root="$1"
+  marketplace="$2"
+  plugin="$3"
+  version="$4"
+  case "$search_root" in
+    /) search_root= ;;
+    */) search_root=${search_root%/} ;;
+  esac
+  printf '%s/plugins/cache/%s/%s/%s\n' \
+    "$search_root" "$marketplace" "$plugin" "$version"
+}
+
+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_from_root_or_empty() {
+  active_root="$1"
+  installed_metadata="$active_root/.superpowers-upstream.json"
+  installed_manifest="$active_root/.codex-plugin/plugin.json"
+  installed_commit=""
+  if [ -f "$installed_metadata" ]; then
+    installed_commit=$(spw_codex_metadata_commit_or_empty "$installed_metadata" || true)
+  fi
+  if [ -z "$installed_commit" ] && [ -f "$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,103 @@
+#!/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"
+  rm -f "$result_file"
+  adapter_exit=0
+  "$SPW_ADAPTER" "$operation" "$@" > "$response_file" || adapter_exit=$?
+
+  args=""
+  if [ -n "$inspect_view" ]; then
+    args="$inspect_view"
+  fi
+  validator_exit=0
+  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" || validator_exit=$?
+  else
+    python3 -S "$SPW_ADAPTER_RESPONSE_VALIDATOR" \
+      --operation "$operation" --adapter-exit "$adapter_exit" \
+      --response "$response_file" --result "$result_file" || validator_exit=$?
+  fi
+  if [ "$validator_exit" -ne 0 ]; then
+    rm -f "$result_file"
+    return 1
+  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_inspect_update_control() {
+  result_file="$1"
+  spw_invoke_adapter inspect "$result_file" update-control -- --view update-control
+}
+
+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,59 @@
+#!/bin/sh
+# Sourced module; callers own set -eu.
+
+spw_die() {
+  echo "error: $*" >&2
+  exit 1
+}
+
+spw_usage_error() {
+  echo "error: $*" >&2
+  exit 2
+}
+
+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_make_workspace() {
+  mktemp -d "$1/$2.XXXXXX"
+}
+
+spw_cleanup_workspace_trap() {
+  _spw_workspace_trap_status=$?
+  trap - 0 HUP INT TERM
+  rm -rf "$_spw_workspace_trap_path" || :
+  exit "$_spw_workspace_trap_status"
+}
+
+spw_install_workspace_trap() {
+  _spw_workspace_trap_path="$1"
+  trap spw_cleanup_workspace_trap 0
+  trap 'exit 129' HUP
+  trap 'exit 130' INT
+  trap 'exit 143' TERM
+}
+
+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
+}