superpowers-manager 0.1.4

package/scripts/prepare

@@ -0,0 +1,136 @@
+#!/bin/sh
+set -eu
+
+root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+. "$root/scripts/lib.sh"
+
+upstream_url="${SUPERPOWERS_UPSTREAM_URL:-$SPW_UPSTREAM_URL_DEFAULT}"
+cache_parent="${SUPERPOWERS_CACHE_DIR:-$root/.cache/upstream}"
+cache="$cache_parent/superpowers"
+plugin_root="${SUPERPOWERS_PLUGIN_ROOT:-$root/plugins/superpowers}"
+manifest_template="${SUPERPOWERS_MANIFEST_TEMPLATE:-$root/plugins/superpowers/.codex-plugin/plugin.template.json}"
+builtin_validator="$root/scripts/validate-generated-plugin.py"
+additional_validator="${SUPERPOWERS_VALIDATOR:-}"
+tmp_parent=$(dirname "$plugin_root")
+tmp_plugin="$tmp_parent/.superpowers.tmp.$$"
+
+cleanup_tmp_plugin() {
+  status=$?
+  trap - 0 HUP INT TERM
+  rm -rf "$tmp_plugin" || :
+  exit "$status"
+}
+
+trap cleanup_tmp_plugin 0
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+requested_ref=$(spw_config_ref "$root")
+
+spw_require_command git
+spw_require_command python3
+[ -f "$manifest_template" ] || spw_die "missing fallback manifest template: $manifest_template"
+[ -f "$builtin_validator" ] || spw_die "missing built-in plugin validator: $builtin_validator"
+
+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"
+if [ -f "$upstream_manifest" ]; then
+  cp "$upstream_manifest" "$tmp_plugin/.codex-plugin/plugin.json"
+else
+  cp "$manifest_template" "$tmp_plugin/.codex-plugin/plugin.json"
+fi
+
+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_apply_manifest_overlay \
+  "$tmp_plugin/.codex-plugin/plugin.json" \
+  "$manager_version"
+
+# The validator must inspect the exact complete tree that will be swapped.
+cp "$manifest_template" "$tmp_plugin/.codex-plugin/plugin.template.json"
+
+if ! python3 -S "$builtin_validator" \
+  --plugin-root "$tmp_plugin" \
+  --source "$upstream_url" \
+  --requested-ref "$requested_ref" \
+  --resolved-ref "$resolved_ref" \
+  --commit "$commit" \
+  --manifest-version "$manager_version" \
+  --upstream-manifest-version "$upstream_manifest_version"; then
+  spw_die "built-in generated plugin validation failed"
+fi
+
+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
+
+# Replace the live tree with a single atomic rename, keeping a backup so a
+# failed swap restores the previous working generated tree (the spec requires
+# that a failed prepare never destroy it). tmp_plugin is a same-filesystem
+# sibling of plugin_root, so the renames cannot fail mid-copy.
+backup="$tmp_parent/.superpowers.bak.$$"
+rm -rf "$backup"
+if [ -e "$plugin_root" ]; then
+  mv "$plugin_root" "$backup"
+fi
+if mv "$tmp_plugin" "$plugin_root"; then
+  rm -rf "$backup"
+else
+  if [ -e "$backup" ]; then
+    mv "$backup" "$plugin_root"
+  fi
+  rm -rf "$tmp_plugin"
+  spw_die "failed to install generated tree into $plugin_root; previous tree restored"
+fi
+
+echo "prepared $resolved_ref at $commit"

package/scripts/probe

@@ -0,0 +1,50 @@
+#!/bin/sh
+set -eu
+
+root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+. "$root/scripts/lib.sh"
+
+codex_bin="${SUPERPOWERS_CODEX:-codex}"
+spw_require_command "$codex_bin"
+spw_require_command python3
+identity_snapshot=$(spw_codex_identity_snapshot "$codex_bin")
+identity_state=$(spw_snapshot_get "$identity_snapshot" identity_state)
+
+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_metadata="$root/plugins/superpowers/.superpowers-upstream.json"
+generated_commit=$(spw_metadata_commit_or_empty "$generated_metadata" || true)
+
+installed_metadata=$(spw_find_installed_metadata || true)
+installed_manifest=$(spw_find_installed_manifest || true)
+installed_commit=""
+if [ -n "$installed_metadata" ]; then
+  installed_commit=$(spw_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
+
+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

@@ -0,0 +1,61 @@
+#!/bin/sh
+set -eu
+
+root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+. "$root/scripts/lib.sh"
+
+codex_bin="${SUPERPOWERS_CODEX:-codex}"
+
+spw_require_command "$codex_bin"
+spw_require_command python3
+
+# Preflight: read and parse BOTH Codex listings before removing anything, so a
+# read/parse failure aborts before any removal (fail closed).
+ownership=$(spw_codex_identity_snapshot "$codex_bin")
+plugin_present=$(spw_snapshot_get "$ownership" manager_plugin)
+marketplace_present=$(spw_snapshot_get "$ownership" manager_marketplace)
+
+# Remove the plugin first, then the marketplace, so an installed plugin is
+# never orphaned from a just-removed marketplace source.
+if [ "$plugin_present" = true ]; then
+  if ! "$codex_bin" plugin remove "$SPW_PLUGIN_ID"; then
+    spw_die "codex plugin remove failed for $SPW_PLUGIN_ID"
+  fi
+  echo "removed plugin $SPW_PLUGIN_ID"
+else
+  echo "plugin not installed; skipping"
+fi
+
+if [ "$marketplace_present" = true ]; then
+  if ! "$codex_bin" plugin marketplace remove "$SPW_MARKETPLACE_NAME"; then
+    spw_die "codex plugin marketplace remove failed for $SPW_MARKETPLACE_NAME"
+  fi
+  echo "removed marketplace $SPW_MARKETPLACE_NAME"
+else
+  echo "marketplace not registered; skipping"
+fi
+
+# Verify-after: re-query and refuse to claim success while either manager
+# target survives. The strict snapshot also records whether legacy state is
+# still present without ever mutating that state.
+ownership=$(spw_codex_identity_snapshot "$codex_bin")
+plugin_present=$(spw_snapshot_get "$ownership" manager_plugin)
+marketplace_present=$(spw_snapshot_get "$ownership" manager_marketplace)
+identity_state=$(spw_snapshot_get "$ownership" identity_state)
+if [ "$plugin_present" = true ]; then
+  spw_die "plugin $SPW_PLUGIN_ID is still installed after removal"
+fi
+if [ "$marketplace_present" = true ]; then
+  spw_die "marketplace $SPW_MARKETPLACE_NAME is still registered after removal"
+fi
+
+case "$identity_state" in
+  legacy|both)
+    printf '%s\n' \
+      'Legacy superpowers-wrapper Codex state remains installed.' \
+      'Run: npx superpowers-wrapper@0.1.1 uninstall'
+    ;;
+esac
+
+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

@@ -0,0 +1,36 @@
+#!/bin/sh
+set -eu
+
+root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+. "$root/scripts/lib.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 Codex 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"
+    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 install"
+    spw_verify_refresh "$desired_commit"
+    ;;
+  needs\ install)
+    sh "$root/scripts/install"
+    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 install"
+    spw_verify_refresh "$desired_commit"
+    ;;
+  *)
+    echo "$probe_output"
+    echo "error: unknown probe status: $status" >&2
+    exit 1
+    ;;
+esac

package/scripts/validate-generated-plugin.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""Validate the wrapper-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 wrapper 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 wrapper-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())