superpowers-manager 0.2.0 → 0.3.0

package/scripts/adapters/codex/validate-generated-plugin.py

@@ -1,314 +0,0 @@
-#!/usr/bin/env python3
-"""Validate the manager-owned generated Superpowers plugin contract."""
-
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import re
-import sys
-from pathlib import Path
-from typing import Any, Sequence
-
-
-SEMVER_RE = re.compile(
-    r"^(0|[1-9][0-9]*)\."
-    r"(0|[1-9][0-9]*)\."
-    r"(0|[1-9][0-9]*)"
-    r"(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)"
-    r"(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?"
-    r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$"
-)
-MAX_JSON_NESTING = 256
-PROVENANCE_KEYS = {
-    "source",
-    "requested_ref",
-    "resolved_ref",
-    "commit",
-    "upstream_manifest_version",
-}
-
-
-def reject_json_constant(constant: str) -> None:
-    raise ValueError(f"non-standard numeric constant: {constant}")
-
-
-def json_nesting_exceeds_limit(value: Any) -> bool:
-    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
-
-
-def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description="Validate a generated Superpowers manager candidate."
-    )
-    parser.add_argument("--plugin-root", required=True)
-    parser.add_argument("--source", required=True)
-    parser.add_argument("--requested-ref", required=True)
-    parser.add_argument("--resolved-ref", required=True)
-    parser.add_argument("--commit", required=True)
-    parser.add_argument("--manifest-version", required=True)
-    parser.add_argument("--upstream-manifest-version", required=True)
-    return parser.parse_args(argv)
-
-
-def load_json_object(path: Path, label: str, errors: list[str]) -> dict[str, Any] | None:
-    try:
-        text = path.read_text(encoding="utf-8")
-    except (OSError, UnicodeError):
-        errors.append(f"{label} is unreadable UTF-8")
-        return None
-    try:
-        value = json.loads(text, parse_constant=reject_json_constant)
-    except RecursionError:
-        errors.append(f"{label} exceeds maximum JSON nesting")
-        return None
-    except (json.JSONDecodeError, ValueError):
-        errors.append(f"{label} must contain valid JSON")
-        return None
-    if json_nesting_exceeds_limit(value):
-        errors.append(f"{label} exceeds maximum JSON nesting")
-        return None
-    if not isinstance(value, dict):
-        errors.append(f"{label} must contain a JSON object")
-        return None
-    return value
-
-
-def validate_local_path(
-    plugin_root: Path,
-    raw_value: Any,
-    label: str,
-    errors: list[str],
-    *,
-    require_directory: bool = False,
-) -> None:
-    if not isinstance(raw_value, str) or not raw_value.strip():
-        errors.append(f"{label} must be a non-empty relative path")
-        return
-    raw_path = Path(raw_value)
-    if raw_path.is_absolute():
-        errors.append(f"{label} must be a relative path")
-        return
-    try:
-        root = plugin_root.resolve()
-        target = (root / raw_path).resolve(strict=False)
-    except (OSError, RuntimeError, ValueError):
-        errors.append(f"{label} could not be resolved")
-        return
-    try:
-        target.relative_to(root)
-    except ValueError:
-        errors.append(f"{label} escapes the plugin root")
-        return
-    try:
-        if not target.exists():
-            errors.append(f"{label} target `{raw_value}` does not exist")
-        elif require_directory and not target.is_dir():
-            errors.append(f"{label} target `{raw_value}` must be a directory")
-    except OSError:
-        errors.append(f"{label} target `{raw_value}` could not be inspected")
-
-
-def validate_manifest(plugin_root: Path, expected_version: str, errors: list[str]) -> None:
-    path = plugin_root / ".codex-plugin" / "plugin.json"
-    if not path.is_file():
-        errors.append("missing required file `.codex-plugin/plugin.json`")
-        return
-    manifest = load_json_object(path, "plugin manifest", errors)
-    if manifest is None:
-        return
-
-    if manifest.get("name") != "superpowers":
-        errors.append("plugin manifest field `name` must equal `superpowers`")
-    version = manifest.get("version")
-    if version != expected_version:
-        errors.append("plugin manifest field `version` must equal expected version")
-    if not isinstance(version, str) or SEMVER_RE.fullmatch(version) is None:
-        errors.append("plugin manifest field `version` must be SemVer 2.0.0")
-    description = manifest.get("description")
-    if not isinstance(description, str) or not description.strip():
-        errors.append("plugin manifest field `description` must be non-empty")
-    if manifest.get("skills") != "./skills/":
-        errors.append("plugin manifest field `skills` must equal `./skills/`")
-    if "hooks" in manifest:
-        errors.append("plugin manifest field `hooks` must be absent")
-
-    validate_local_path(
-        plugin_root,
-        manifest.get("skills"),
-        "plugin manifest field `skills`",
-        errors,
-        require_directory=True,
-    )
-    if "apps" in manifest:
-        validate_local_path(plugin_root, manifest["apps"], "plugin manifest field `apps`", errors)
-    if "mcpServers" in manifest:
-        mcp_servers = manifest["mcpServers"]
-        if isinstance(mcp_servers, str):
-            validate_local_path(
-                plugin_root, mcp_servers, "plugin manifest field `mcpServers`", errors
-            )
-        elif not isinstance(mcp_servers, dict):
-            errors.append("plugin manifest field `mcpServers` must be a string or object")
-
-    if "interface" not in manifest:
-        return
-    interface = manifest["interface"]
-    if not isinstance(interface, dict):
-        errors.append("plugin manifest field `interface` must be an object")
-        return
-    for field in ("composerIcon", "logo", "logoDark"):
-        if field in interface:
-            validate_local_path(
-                plugin_root,
-                interface[field],
-                f"plugin manifest field `interface.{field}`",
-                errors,
-            )
-    if "screenshots" in interface:
-        screenshots = interface["screenshots"]
-        if not isinstance(screenshots, list):
-            errors.append("plugin manifest field `interface.screenshots` must be an array")
-        else:
-            for index, value in enumerate(screenshots):
-                validate_local_path(
-                    plugin_root,
-                    value,
-                    f"plugin manifest field `interface.screenshots[{index}]`",
-                    errors,
-                )
-
-
-def validate_skill_frontmatter(skill_md: Path, skill_name: str, errors: list[str]) -> None:
-    try:
-        contents = skill_md.read_text(encoding="utf-8")
-    except (OSError, UnicodeError):
-        errors.append(f"skill `{skill_name}` has unreadable UTF-8 `SKILL.md`")
-        return
-    if not contents:
-        errors.append(f"skill `{skill_name}` has empty `SKILL.md`")
-        return
-    lines = contents.splitlines()
-    if not lines or lines[0] != "---":
-        errors.append(f"skill `{skill_name}` must start with `---`")
-        return
-    try:
-        closing_index = lines.index("---", 1)
-    except ValueError:
-        errors.append(f"skill `{skill_name}` frontmatter is not closed")
-        return
-    frontmatter = lines[1:closing_index]
-    for key in ("name", "description"):
-        matches = [line for line in frontmatter if line.startswith(f"{key}:")]
-        if len(matches) != 1:
-            errors.append(
-                f"skill `{skill_name}` frontmatter must contain exactly one top-level `{key}:`"
-            )
-            continue
-        value = matches[0].split(":", 1)[1].strip()
-        if value in {"", "''", '\"\"'} or value.startswith("#"):
-            errors.append(f"skill `{skill_name}` frontmatter field `{key}` must be non-empty")
-
-
-def validate_tree(plugin_root: Path, errors: list[str]) -> None:
-    required_files = (
-        ".codex-plugin/plugin.template.json",
-        ".superpowers-upstream.json",
-        "LICENSE",
-        "README.md",
-        "CODE_OF_CONDUCT.md",
-    )
-    for relative in required_files:
-        if not (plugin_root / relative).is_file():
-            errors.append(f"missing required file `{relative}`")
-    if os.path.lexists(plugin_root / "hooks"):
-        errors.append("generated plugin must not contain `hooks/`")
-
-    skills_root = plugin_root / "skills"
-    if not skills_root.is_dir():
-        errors.append("missing required directory `skills/`")
-        return
-    try:
-        skill_dirs = sorted(
-            path
-            for path in skills_root.iterdir()
-            if not path.name.startswith(".") and path.is_dir()
-        )
-    except OSError:
-        errors.append("skills directory could not be enumerated")
-        return
-    if not skill_dirs:
-        errors.append("`skills/` must contain at least one skill directory")
-        return
-    for skill_dir in skill_dirs:
-        skill_md = skill_dir / "SKILL.md"
-        if not skill_md.is_file():
-            errors.append(f"skill `{skill_dir.name}` is missing `SKILL.md`")
-            continue
-        validate_skill_frontmatter(skill_md, skill_dir.name, errors)
-
-
-def validate_provenance(args: argparse.Namespace, plugin_root: Path, errors: list[str]) -> None:
-    path = plugin_root / ".superpowers-upstream.json"
-    if not path.is_file():
-        return
-    provenance = load_json_object(path, "provenance", errors)
-    if provenance is None:
-        return
-    if set(provenance) != PROVENANCE_KEYS:
-        errors.append("provenance keys do not match the manager-owned contract")
-    expected = {
-        "source": args.source,
-        "requested_ref": args.requested_ref,
-        "resolved_ref": args.resolved_ref,
-        "commit": args.commit,
-        "upstream_manifest_version": args.upstream_manifest_version,
-    }
-    for key, value in expected.items():
-        if provenance.get(key) != value:
-            errors.append(f"provenance field `{key}` does not match expected value")
-    if re.fullmatch(r"[0-9a-f]{40}", args.commit) is None:
-        errors.append("commit must be 40 lowercase hexadecimal characters")
-
-
-def validate(args: argparse.Namespace) -> list[str]:
-    errors: list[str] = []
-    try:
-        plugin_root = Path(args.plugin_root).expanduser().resolve()
-    except (OSError, RuntimeError, ValueError):
-        errors.append("plugin root could not be resolved")
-        return errors
-    validate_manifest(plugin_root, args.manifest_version, errors)
-    validate_tree(plugin_root, errors)
-    validate_provenance(args, plugin_root, errors)
-    return errors
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    args = parse_args(argv)
-    errors = validate(args)
-    if errors:
-        print("Generated plugin validation failed:", file=sys.stderr)
-        for error in errors:
-            print(f"- {error}", file=sys.stderr)
-        return 1
-    print(f"generated plugin validation passed: {args.plugin_root}")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/scripts/core/adapter.sh

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

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

package/scripts/core/lifecycle.sh

@@ -1,141 +0,0 @@
-#!/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_probe_field() {
-  printf '%s\n' "$1" | awk -F= -v key="$2" '$1 == key { print $2 }'
-}
-
-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_require_managed_update_control() {
-  case "$1" in
-    managed) return 0 ;;
-    unsupported)
-      spw_die "adapter cannot guarantee manager-controlled updates"
-      ;;
-    *) spw_die "unknown adapter update-control capability: $1" ;;
-  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
-}