Skip to content

richfrem/agent-plugins-skills / plugins/agent-extension-authoring/.apm/skills/packaging-with-apm

packaging-with-apm

Flagged

Packages, installs and distributes agent extensions with APM (Agent Package Manager). Use when the user wants to create a new APM package, convert or migrate an existing plugin to APM and check it installs cleanly, compile a package into AGENTS.md, CLAUDE.md or GEMINI.md, install, update, pin or roll back packages globally or per project, or create a plugin marketplace catalog (marketplace.json). Not for authoring a single skill, plugin, sub-agent or rule (use the authoring-* skills).

FileKindSize
SKILL.mdskill md5.3 KB
evals/evals.jsonconfig2.7 KB
examples/marketplace.jsonconfig45 B
references/acceptance-criteria.mdmarkdown4.6 KB
references/agent-package-manager-overview.mdmarkdown28.7 KB
references/apm-alignment-fixes.mdmarkdown5.3 KB
references/diagrams/packaging-with-apm-flow.mmdother590 B
references/fallback-tree.mdmarkdown1.8 KB
references/legacy-plugin-conversion-guide.mdmarkdown15.4 KB
references/marketplace-architecture.mdmarkdown1.5 KB
references/marketplace-schema.mdmarkdown2.5 KB
references/marketplace.mdmarkdown11.5 KB
references/modes/compile-apm-package.mdmarkdown1.7 KB
references/modes/convert-plugin-to-apm.mdmarkdown7.3 KB
references/modes/create-apm-package.mdmarkdown1.7 KB
references/modes/install-apm-package.mdmarkdown4.3 KB
references/modes/manage-marketplace.mdmarkdown2.1 KB
requirements-dev.inother657 B
requirements-dev.txtmarkdown3.3 KB
requirements.inother148 B
requirements.txtmanifest171 B
scripts/apm_build_pipeline.pyscript35.1 KB
scripts/apm_consumer.pyscript11.3 KB
scripts/apply_symlink_repairs.pyscript1.7 KB
scripts/apply_symlink_repairs.shscript40 B
scripts/audit_marketplace_sources.pyscript2.5 KB
scripts/check_for_broken_symlinks.pyexecutablescript6.6 KB
scripts/convert_symlinks_to_manifest.pyscript6.7 KB
scripts/decouple_agent_paths.pyscript9.1 KB
scripts/fix_inside_plugin_symlinks.pyscript11.3 KB
scripts/materialize_copies.pyscript5.3 KB
scripts/migrate_to_apm.pyscript16.4 KB
scripts/scaffold_apm.pyscript8.6 KB
scripts/validate_apm_package.pyscript5.7 KB
tests/test_apm_build_pipeline.pyscript10.2 KB
tests/test_apm_consumer.pyscript4.8 KB
tests/test_audit_decoupled_state.pyscript8.6 KB
tests/test_convert_symlinks_to_manifest.pyscript5.3 KB
tests/test_decouple_agent_paths.pyscript4.8 KB
tests/test_scaffold_apm.pyscript1.7 KB

scripts/apm_build_pipeline.py

View on GitHub
#!/usr/bin/env python3
"""
apm_build_pipeline.py (CLI)
=====================================

Purpose:
    Build-time APM packaging pipeline for one plugin (docs/plans/apm_migration_plan.md,
    Section 4). Runs five stages: inspect -> normalize -> validate -> package -> test deploy.
    All output goes to an isolated staging directory (default build/staging/<plugin>/);
    the authoring source tree is never modified.

    Symlinks are discovered from the git index (mode 120000) and their targets are read
    from the git blob, so a Windows checkout with core.symlinks=false (where each symlink
    is a short text stub) is dereferenced exactly like a real symlink.

    Symlink-free sharing: symlinks.json entries with strategy "copy" name one canonical
    source file and the skill paths that need a copy; the build creates those copies in
    staging only (plan Section 10.3), and --pack produces the bundle consumers install.

Usage:
    python3 apm_build_pipeline.py --plugin plugins/dev-utils
    python3 apm_build_pipeline.py --plugin plugins/dev-utils --skip-deploy
    python3 apm_build_pipeline.py --plugin plugins/dev-utils --pack
    python3 apm_build_pipeline.py --plugin plugins/dev-utils --apm /path/to/apm --targets copilot,claude

Outputs:
    <build-dir>/<plugin>/                 staged, symlink-free package with apm.yml
    <build-dir>/<plugin>.report.json      audit manifest + validation + deploy results
    <deploy-dir>/<plugin>/                throwaway fixture repo used by test deploy
    <dist-dir>/<plugin>-<version>.zip     installable bundle (--pack only)

Exit codes: 0 all stages passed, 1 validation or deploy errors, 2 usage error.

Key Input Dependencies:
    - git (repo must be a git work tree; symlinks are read from the index)
    - <plugin>/.claude-plugin/plugin.json or <plugin>/plugin.yaml (metadata; optional)
    - symlinks.json at the repo root (copy-manifest entries with strategy "copy"; optional)
    - APM CLI on PATH or via --apm (test deploy stage only; pinned in
      plugins/agent-extension-authoring/skills/packaging-with-apm/requirements-dev.in)
    - PyYAML

Function Index:
    - git_symlink_entries(repo_root, plugin_rel) -> list[dict]
    - _still_a_link(path, link_text) -> bool
    - load_plugin_metadata(plugin_dir) -> dict
    - copy_manifest_entries(repo_root, plugin_rel) -> list[dict]
    - inspect_plugin(repo_root, plugin_dir) -> dict
    - _copy_ignore(directory, names) -> set[str]
    - _sha256(path) -> str
    - _materialize_link(staged_path, target_abs) -> None
    - normalize_plugin(inspection, staging_dir) -> dict
    - _materialize_copies(inspection, staging_dir) -> list[dict]
    - _finding(level, check, path, detail, suggestion) -> dict
    - _parse_frontmatter(text) -> dict
    - _check_skill_frontmatter(staged_dir) -> list[dict]
    - _iter_relative_links(text) -> list[str]
    - _check_unrewritten_paths(staged_dir) -> list[dict]
    - _check_relative_links(staged_dir) -> list[dict]
    - _check_plugin_config(staged_dir) -> list[dict]
    - _check_hook_scripts(staged_dir) -> list[dict]
    - _check_link_entries(normalized) -> list[dict]
    - _check_no_symlinks(staged_dir) -> list[dict]
    - validate_package(staged_dir, normalized) -> dict
    - package_plugin(staged_dir, inspection, targets) -> dict
    - _run_apm(apm_bin, args, cwd) -> dict
    - _deployed_skill_dirs(fixture, skill) -> list[Path]
    - _check_deployed_skills(fixture, staged_dir, skills) -> list[dict]
    - _links_resolve(md) -> bool
    - run_test_deploy(staged_dir, fixture, targets, apm_bin, skills) -> dict
    - pack_plugin(staged_dir, dist_dir, apm_bin) -> dict
    - run_pipeline(args) -> dict
    - main() -> None
"""

import argparse
import hashlib
import json
import os
import re
import shutil
import subprocess
import sys
from pathlib import Path

import yaml

SYMLINK_MODE = "120000"
DEFAULT_TARGETS = ["claude", "copilot", "agy", "codex"]
# CLI target names that a package apm.yml spells differently (APM 0.33.0).
MANIFEST_TARGET_NAMES = {"agents": "agent-skills", "agy": "antigravity"}
COPY_IGNORE = {"__pycache__", ".DS_Store"}
DEPLOYED_DIRS = ("skills", "agents", "commands", ".apm/skills", ".apm/agents", ".apm/commands")
SKIP_LINK_PREFIXES = ("http://", "https://", "mailto:", "#", "file://")


def _prim_dir(root: Path, sub: str) -> Path:
    """Return <root>/.apm/<sub> if it exists, else <root>/<sub>."""
    apm_sub = root / ".apm" / sub
    return apm_sub if apm_sub.is_dir() else (root / sub)


# ---------------------------------------------------------------------------
# Stage 1: Inspect
# ---------------------------------------------------------------------------

# Read every symlink under the plugin from the git index, with its link text.
def git_symlink_entries(repo_root: Path, plugin_rel: str) -> list[dict]:
    """Return [{path, link_text}] for each mode-120000 entry under plugin_rel.

    The link text comes from the git blob, not the filesystem, so the result is the
    same on a checkout where symlinks were materialized as plain text stubs.
    """
    listing = subprocess.run(
        ["git", "-C", str(repo_root), "ls-files", "-s", "--", plugin_rel],
        capture_output=True, text=True, check=True,
    ).stdout
    entries = []
    for line in listing.splitlines():
        meta, path = line.split("\t", 1)
        mode, sha, _stage = meta.split()
        if mode == SYMLINK_MODE:
            entries.append({"path": path, "sha": sha})
    if not entries:
        return []
    batch = "\n".join(e["sha"] for e in entries) + "\n"
    out = subprocess.run(
        ["git", "-C", str(repo_root), "cat-file", "--batch"],
        input=batch.encode(), capture_output=True, check=True,
    ).stdout
    pos = 0
    for entry in entries:
        header_end = out.index(b"\n", pos)
        size = int(out[pos:header_end].split()[2])
        entry["link_text"] = out[header_end + 1:header_end + 1 + size].decode("utf-8")
        pos = header_end + 1 + size + 1
        del entry["sha"]
    return [e for e in entries if _still_a_link(repo_root / e["path"], e["link_text"])]


# An index symlink still counts only while the working tree holds the link itself (or, on
# a Windows checkout, its text stub); a path already replaced by real content is left alone.
def _still_a_link(path: Path, link_text: str) -> bool:
    """True if path is a symlink, or a regular file whose whole content is the link text."""
    if path.is_symlink():
        return True
    if not path.is_file() or path.stat().st_size > 4096:
        return False
    return path.read_text(encoding="utf-8", errors="replace").strip() == link_text.strip()


# Load plugin name/version/description/author from the plugin manifest.
def load_plugin_metadata(plugin_dir: Path) -> dict:
    """Read .claude-plugin/plugin.json, falling back to plugin.yaml, then the folder name."""
    data: dict = {}
    json_manifest = plugin_dir / ".claude-plugin" / "plugin.json"
    yaml_manifest = plugin_dir / "plugin.yaml"
    if json_manifest.is_file():
        data = json.loads(json_manifest.read_text(encoding="utf-8"))
    elif yaml_manifest.is_file():
        data = yaml.safe_load(yaml_manifest.read_text(encoding="utf-8")) or {}
    author = data.get("author", "Unknown")
    if isinstance(author, dict):
        author = author.get("name", "Unknown")
    return {
        "name": data.get("name", plugin_dir.name),
        "version": str(data.get("version", "0.1.0")),
        "description": data.get("description", f"APM package for {plugin_dir.name}"),
        "author": author,
        "license": data.get("license", ""),
    }


# Read copy-manifest entries (symlinks.json, strategy "copy") whose destination is in the plugin.
def copy_manifest_entries(repo_root: Path, plugin_rel: str) -> list[dict]:
    """Return [{src, dst}] entries that the build must materialize as physical copies.

    This is the symlink-free form of hub-and-spoke sharing (plan Section 10.3): one
    canonical file in source, listed copies created only in staging.
    """
    manifest = repo_root / "symlinks.json"
    if not manifest.is_file():
        return []
    links = json.loads(manifest.read_text(encoding="utf-8")).get("links", [])
    prefix = plugin_rel.rstrip("/") + "/"
    return [{"src": e["src"], "dst": e["dst"]} for e in links
            if e.get("strategy") == "copy" and e.get("dst", "").startswith(prefix)]


# Stage 1: scan layout, manifest and symlinks without touching anything.
def inspect_plugin(repo_root: Path, plugin_dir: Path) -> dict:
    """Discover skills, agents, commands, hooks, rules and git symlinks for one plugin."""
    plugin_rel = plugin_dir.relative_to(repo_root).as_posix()
    skills_dir = _prim_dir(plugin_dir, "skills")
    skills = sorted(p.parent.name for p in skills_dir.glob("*/SKILL.md")) if skills_dir.is_dir() else []

    def names(sub: str, pattern: str) -> list[str]:
        folder = _prim_dir(plugin_dir, sub) if sub in ("agents", "commands", "hooks") else (plugin_dir / sub)
        return sorted(p.name for p in folder.glob(pattern)) if folder.is_dir() else []

    return {
        "repo_root": str(repo_root),
        "plugin_dir": str(plugin_dir),
        "plugin_rel": plugin_rel,
        "metadata": load_plugin_metadata(plugin_dir),
        "skills": skills,
        "agents": names("agents", "*.md"),
        "commands": names("commands", "*.md"),
        "hooks": names("hooks", "*"),
        "rules": names("rules", "*.md"),
        "symlinks": git_symlink_entries(repo_root, plugin_rel),
        "copies": copy_manifest_entries(repo_root, plugin_rel),
    }


# ---------------------------------------------------------------------------
# Stage 2: Normalize
# ---------------------------------------------------------------------------

# shutil.copytree ignore callback: drop caches and OS noise from the staged copy.
def _copy_ignore(directory: str, names: list[str]) -> set[str]:
    """Return the names in directory that must not be staged."""
    return {n for n in names if n in COPY_IGNORE or n.endswith(".pyc")}


# Content hash used by the SHA-256 acceptance check (plan Section 2).
def _sha256(path: Path) -> str:
    """Return the hex SHA-256 of a file's bytes."""
    return hashlib.sha256(path.read_bytes()).hexdigest()


# Replace a staged link (or text stub) with a physical copy of its target.
def _materialize_link(staged_path: Path, target_abs: Path) -> None:
    """Remove whatever is at staged_path and copy the target file or directory there."""
    if staged_path.is_symlink() or staged_path.is_file():
        staged_path.unlink()
    elif staged_path.is_dir():
        shutil.rmtree(staged_path)
    if target_abs.is_dir():
        shutil.copytree(target_abs, staged_path, ignore=_copy_ignore)
    else:
        shutil.copy2(target_abs, staged_path)


# Stage 2: copy the plugin into staging and dereference every git symlink there.
def normalize_plugin(inspection: dict, staging_dir: Path) -> dict:
    """Stage the plugin and resolve each symlink against the source tree.

    Returns an audit manifest: one entry per symlink with its resolved target, whether
    the target stays inside the plugin, the staged SHA-256 and a status of
    'resolved' or 'broken'.
    """
    repo_root = Path(inspection["repo_root"])
    plugin_dir = Path(inspection["plugin_dir"])
    if staging_dir.exists():
        shutil.rmtree(staging_dir)
    staging_dir.parent.mkdir(parents=True, exist_ok=True)
    shutil.copytree(plugin_dir, staging_dir, symlinks=True, ignore=_copy_ignore)

    manifest = []
    for link in inspection["symlinks"]:
        source_link = repo_root / link["path"]
        target_abs = Path(os.path.normpath(source_link.parent / link["link_text"]))
        rel_in_plugin = source_link.relative_to(plugin_dir)
        staged_path = staging_dir / rel_in_plugin
        entry = {
            "kind": "symlink",
            "path": rel_in_plugin.as_posix(),
            "link_text": link["link_text"],
            "target": os.path.relpath(target_abs, repo_root),
            "inside_plugin": target_abs.is_relative_to(plugin_dir),
        }
        if not target_abs.exists():
            # Unresolvable: drop the dangling link from staging; the audit manifest keeps it.
            if staged_path.is_symlink() or staged_path.is_file():
                staged_path.unlink()
            entry["status"] = "broken"
        else:
            _materialize_link(staged_path, target_abs)
            entry["status"] = "resolved"
            if target_abs.is_file():
                entry["target_sha256"] = _sha256(target_abs)
                entry["staged_sha256"] = _sha256(staged_path)
        manifest.append(entry)
    manifest += _materialize_copies(inspection, staging_dir)
    return {"staging_dir": str(staging_dir), "links": manifest}


# Create the physical copies listed in the copy manifest inside staging.
def _materialize_copies(inspection: dict, staging_dir: Path) -> list[dict]:
    """Copy each manifest src to its dst in staging; return audit entries like symlinks."""
    repo_root = Path(inspection["repo_root"])
    plugin_dir = Path(inspection["plugin_dir"])
    entries = []
    for item in inspection.get("copies", []):
        target_abs = (repo_root / item["src"]).resolve()
        rel_in_plugin = (repo_root / item["dst"]).relative_to(plugin_dir)
        staged_path = staging_dir / rel_in_plugin
        entry = {"kind": "copy", "path": rel_in_plugin.as_posix(), "link_text": item["src"],
                 "target": item["src"], "inside_plugin": target_abs.is_relative_to(plugin_dir.resolve())}
        if not target_abs.is_file():
            entry["status"] = "broken"
        else:
            staged_path.parent.mkdir(parents=True, exist_ok=True)
            _materialize_link(staged_path, target_abs)
            entry.update(status="resolved", target_sha256=_sha256(target_abs),
                         staged_sha256=_sha256(staged_path))
        entries.append(entry)
    return entries


# ---------------------------------------------------------------------------
# Stage 3: Validate
# ---------------------------------------------------------------------------

# Standard fix for every finding type (full text: references/apm-alignment-fixes.md).
# Each finding carries its fix id so the same misalignment is always fixed the same way.
STANDARD_FIXES = {
    "broken_symlink": "SF-1 delete the dummy symlink; cite the canonical file with a relative link",
    "cross_plugin_symlink": "SF-2 delete the symlink; reference the other plugin's skill by name (ADR-001)",
    "broken_relative_link": "SF-3 fix the markdown link so it resolves to a file inside the plugin",
    "link_escapes_package": "SF-3 link only to files inside the plugin; reference other plugins' skills by name",
    "path_not_rewritten": "SF-8 use a markdown link for documents; keep scripts a skill runs inside that skill",
    "symlink_in_package": "SF-4 re-run normalize; report if the link is not in the git index",
    "sha256_mismatch": "SF-4 re-run normalize; report if the link is not in the git index",
    "frontmatter_name": "SF-5 set frontmatter name to the skill folder name",
    "frontmatter_description": "SF-5 add a third-person description to the frontmatter",
    "skill_not_deployed": "SF-6 check the skill folder has SKILL.md with valid frontmatter",
    "deployed_content_mismatch": "SF-6 compare staged vs deployed file; report to APM if links do not resolve",
    "rules_not_deployed": "SF-9 none in the package: setup copies needed rules into .agent/rules/ (AGENTS.md lists them)",
    "lsp_config_invalid": "SF-10 use APM's flat lsp.json format ({name: {command, ...}}) or delete an empty file",
    "hook_script_harness_path": "SF-11 use Path(__file__) for own files and a harness-neutral state path (e.g. context/)",
    "agent_mirrors_skill": "SF-12 write the agent as its own short definition that uses the skill by name",
    "link_rewritten_by_apm": "none (expected: APM rewrites cross-skill links into apm_modules/)",
    "apm_install_failed": "SF-7 read the APM error; map target names (agents -> agent-skills in apm.yml)",
    "uninstall_left_files": "SF-6 compare lockfile deployed files against the fixture",
}


# Build one finding with its standard fix attached.
def _finding(level: str, check: str, path: str, detail: object, suggestion: str = "") -> dict:
    """Return a finding dict; suggestion is a concrete replacement when one can be computed."""
    finding = {"level": level, "check": check, "path": path, "detail": detail,
               "fix": STANDARD_FIXES.get(check, "")}
    if suggestion:
        finding["suggestion"] = suggestion
    return finding


# Minimal YAML frontmatter reader for SKILL.md files.
def _parse_frontmatter(text: str) -> dict:
    """Return the YAML frontmatter dict, or {} if the file has none or it is invalid."""
    if not text.startswith("---"):
        return {}
    end = text.find("\n---", 3)
    if end == -1:
        return {}
    try:
        return yaml.safe_load(text[3:end]) or {}
    except yaml.YAMLError:
        return {}


# Each staged skill must declare a name matching its folder and a description.
def _check_skill_frontmatter(staged_dir: Path) -> list[dict]:
    """Return findings for SKILL.md files with missing or mismatched frontmatter."""
    findings = []
    skills_dir = _prim_dir(staged_dir, "skills")
    for skill_md in sorted(skills_dir.glob("*/SKILL.md")):
        meta = _parse_frontmatter(skill_md.read_text(encoding="utf-8", errors="replace"))
        rel = skill_md.relative_to(staged_dir).as_posix()
        if meta.get("name") != skill_md.parent.name:
            findings.append(_finding("error", "frontmatter_name", rel,
                                     f"name={meta.get('name')!r}, folder={skill_md.parent.name!r}"))
        if not meta.get("description"):
            findings.append(_finding("error", "frontmatter_description", rel, "missing description"))
    return findings


# Extract relative markdown link targets, ignoring fenced and inline code.
def _iter_relative_links(text: str) -> list[str]:
    """Return link targets from [text](target) that are relative file paths."""
    text = re.sub(r"```.*?```", "", text, flags=re.DOTALL)
    text = re.sub(r"`[^`\n]*`", "", text)
    links = []
    for raw in re.findall(r"\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)", text):
        if raw.startswith(SKIP_LINK_PREFIXES) or raw.startswith("<"):
            continue
        target = raw.split("#", 1)[0]
        if target:
            links.append(target)
    return links


# Every relative markdown link in deployed content must resolve inside the plugin package.
# APM copies only the skill folder, but rewrites markdown links that leave it to point into
# its package cache (apm_modules/ or ~/.apm/apm_modules/), so links to sibling skills and
# plugin-root files work after install. Links that leave the plugin are not rewritten.
def _check_relative_links(staged_dir: Path) -> list[dict]:
    """Return findings for deployed-content links that are broken or leave the package."""
    findings = []
    root = staged_dir.resolve()
    for deploy_root in (staged_dir / d for d in DEPLOYED_DIRS):
        if not deploy_root.is_dir():
            continue
        for md in sorted(deploy_root.rglob("*.md")):
            if md.is_symlink() or not md.is_file():
                continue
            rel = md.relative_to(staged_dir).as_posix()
            for target in _iter_relative_links(md.read_text(encoding="utf-8", errors="replace")):
                resolved = (md.parent / target).resolve()
                if not resolved.is_relative_to(root):
                    findings.append(_finding("error", "link_escapes_package", rel, target))
                elif not resolved.exists():
                    findings.append(_finding("error", "broken_relative_link", rel, target))
    return findings


# Paths outside markdown links (inline code, code blocks, plain text) are not rewritten by
# APM, so any such path that climbs out of its skill folder breaks after install.
def _check_unrewritten_paths(staged_dir: Path) -> list[dict]:
    """Return warnings for ../ paths outside markdown links that leave their skill folder."""
    findings = []
    link_spans = re.compile(r"\]\([^)]*\)")
    path_token = re.compile(r"(?:\.\./)+[\w./-]+")
    skills_dir = _prim_dir(staged_dir, "skills")
    for skill_dir in sorted(p for p in skills_dir.glob("*") if p.is_dir()):
        root = skill_dir.resolve()
        for md in sorted(skill_dir.rglob("*.md")):
            if md.is_symlink() or not md.is_file():
                continue
            text = link_spans.sub("", md.read_text(encoding="utf-8", errors="replace"))
            for token in sorted(set(path_token.findall(text))):
                if not (md.parent / token).resolve().is_relative_to(root):
                    findings.append(_finding("warning", "path_not_rewritten",
                                             md.relative_to(staged_dir).as_posix(), token))
    return findings


# Plugin-level config that APM does not deploy or cannot read.
def _check_plugin_config(staged_dir: Path) -> list[dict]:
    """Return findings for rules/ folders and lsp.json files APM will not use."""
    findings = []
    if (staged_dir / "rules").is_dir():
        count = len(list((staged_dir / "rules").glob("*.md")))
        findings.append(_finding("info", "rules_not_deployed", "rules/", f"{count} rule files"))
    for name in ("lsp.json", ".lsp.json"):
        path = staged_dir / name
        if not path.is_file():
            continue
        try:
            servers = json.loads(path.read_text(encoding="utf-8"))
        except json.JSONDecodeError as exc:
            findings.append(_finding("warning", "lsp_config_invalid", name, f"invalid JSON: {exc}"))
            continue
        bad = [k for k, v in servers.items() if not (isinstance(v, dict) and v.get("command"))]
        if bad:
            findings.append(_finding("warning", "lsp_config_invalid", name, f"entries without command: {bad}"))
    return findings


# Hook scripts run under every target harness, so they must not hardcode one harness's folder.
def _check_hook_scripts(staged_dir: Path) -> list[dict]:
    """Return warnings for hook scripts (from .apm/hooks/hooks.json or hooks/hooks.json) that name .claude/ or .agents/."""
    hooks_json = _prim_dir(staged_dir, "hooks") / "hooks.json"
    if not hooks_json.is_file():
        return []
    commands = re.findall(r"\$\{CLAUDE_PLUGIN_ROOT\}/([\w./-]+\.py)", hooks_json.read_text(encoding="utf-8"))
    findings = []
    for rel in sorted(set(commands)):
        script = staged_dir / rel
        if not script.is_file():
            continue
        hits = sorted(set(re.findall(r"\.(?:claude|agents)/[\w./-]*", script.read_text(encoding="utf-8", errors="replace"))))
        if hits:
            findings.append(_finding("warning", "hook_script_harness_path", rel, hits[:5]))
    return findings


# Symlink audit: broken targets, cross-plugin targets, and hash mismatches.
def _check_link_entries(normalized: dict) -> list[dict]:
    """Return findings from the normalize audit manifest."""
    findings = []
    for entry in normalized["links"]:
        if entry["status"] == "broken":
            findings.append(_finding("error", "broken_symlink", entry["path"],
                                     f"target {entry['target']} does not exist"))
            continue
        if entry["path"].startswith("agents/") and entry["target"].endswith("SKILL.md"):
            findings.append(_finding("warning", "agent_mirrors_skill", entry["path"],
                                     f"agent file is a copy of {entry['target']}; its skill-relative links break in agents/"))
        if not entry["inside_plugin"]:
            findings.append(_finding("error", "cross_plugin_symlink", entry["path"],
                                     f"target {entry['target']} is outside the plugin"))
        if "target_sha256" in entry and entry["target_sha256"] != entry["staged_sha256"]:
            findings.append(_finding("error", "sha256_mismatch", entry["path"],
                                     "staged file differs from its source target"))
    return findings


# The staged package must contain no symlinks at all.
def _check_no_symlinks(staged_dir: Path) -> list[dict]:
    """Return a finding for every symlink left in the staged tree."""
    findings = []
    for dirpath, dirnames, filenames in os.walk(staged_dir):
        for name in dirnames + filenames:
            path = Path(dirpath) / name
            if path.is_symlink():
                findings.append(_finding("error", "symlink_in_package",
                                         path.relative_to(staged_dir).as_posix(),
                                         f"-> {os.readlink(path)}"))
    return findings


# Stage 3: run every check and summarize.
def validate_package(staged_dir: Path, normalized: dict) -> dict:
    """Return {passed, error_count, warning_count, findings} for the staged package."""
    findings = (
        _check_link_entries(normalized)
        + _check_no_symlinks(staged_dir)
        + _check_skill_frontmatter(staged_dir)
        + _check_relative_links(staged_dir)
        + _check_unrewritten_paths(staged_dir)
        + _check_plugin_config(staged_dir)
        + _check_hook_scripts(staged_dir)
    )
    errors = sum(1 for f in findings if f["level"] == "error")
    return {
        "passed": errors == 0,
        "error_count": errors,
        "warning_count": sum(1 for f in findings if f["level"] == "warning"),
        "findings": findings,
    }


# ---------------------------------------------------------------------------
# Stage 4: Package
# ---------------------------------------------------------------------------

# Stage 4: write apm.yml into the staged package (never into the source plugin).
def package_plugin(staged_dir: Path, inspection: dict, targets: list[str]) -> dict:
    """Write <staged_dir>/apm.yml from the plugin metadata and requested targets."""
    meta = inspection["metadata"]
    manifest = {
        "name": meta["name"],
        "version": meta["version"],
        "description": meta["description"],
        "author": {"name": meta["author"]},
        "targets": [MANIFEST_TARGET_NAMES.get(t, t) for t in targets],
        # apm pack only produces an installable bundle when a dependencies block exists.
        "dependencies": {},
    }
    if meta.get("license"):
        manifest["license"] = meta["license"]
    apm_yml = staged_dir / "apm.yml"
    apm_yml.write_text(yaml.safe_dump(manifest, sort_keys=False), encoding="utf-8")
    return {"apm_yml": str(apm_yml), "manifest": manifest}


# ---------------------------------------------------------------------------
# Stage 5: Test Deploy
# ---------------------------------------------------------------------------

# Run one APM command and capture its result.
def _run_apm(apm_bin: str, args: list[str], cwd: Path) -> dict:
    """Run apm with args in cwd; return {cmd, exit_code, output_tail}."""
    env = dict(os.environ, NO_COLOR="1")
    proc = subprocess.run([apm_bin, *args], cwd=cwd, capture_output=True, text=True, env=env)
    output = (proc.stdout + proc.stderr).strip().splitlines()
    return {"cmd": " ".join(["apm", *args]), "exit_code": proc.returncode, "output_tail": output[-15:]}


# Project-scope locations where APM may deploy a skill.
def _deployed_skill_dirs(fixture: Path, skill: str) -> list[Path]:
    """Return existing deployed copies of one skill inside the fixture repo."""
    candidates = [fixture / ".agents" / "skills" / skill,
                  fixture / ".claude" / "skills" / skill,
                  fixture / ".github" / "skills" / skill]
    return [c for c in candidates if (c / "SKILL.md").is_file()]


# Every staged skill must deploy, and each deployed file must match the staged bytes.
def _check_deployed_skills(fixture: Path, staged_dir: Path, skills: list[str]) -> list[dict]:
    """Return findings for missing skills or deployed files that differ from staging."""
    findings = []
    skills_dir = _prim_dir(staged_dir, "skills")
    for skill in skills:
        deployed = _deployed_skill_dirs(fixture, skill)
        if not deployed:
            findings.append(_finding("error", "skill_not_deployed", skill, ""))
            continue
        staged_skill = skills_dir / skill
        for copy in deployed:
            for f in copy.rglob("*"):
                src = staged_skill / f.relative_to(copy)
                if not (f.is_file() and src.is_file()) or _sha256(f) == _sha256(src):
                    continue
                rel = f.relative_to(fixture).as_posix()
                if f.suffix == ".md" and _links_resolve(f):
                    findings.append(_finding("info", "link_rewritten_by_apm", rel,
                                             "APM rewrote cross-skill links into apm_modules/; all resolve"))
                else:
                    findings.append(_finding("error", "deployed_content_mismatch", rel, ""))
    return findings


# True when every relative markdown link in a deployed file resolves on disk.
def _links_resolve(md: Path) -> bool:
    """Check the relative links of one deployed markdown file."""
    text = md.read_text(encoding="utf-8", errors="replace")
    return all((md.parent / t).resolve().exists() for t in _iter_relative_links(text))


# Stage 5: dry-run, install, verify, then uninstall into a throwaway fixture repo.
def run_test_deploy(staged_dir: Path, fixture: Path, targets: list[str], apm_bin: str, skills: list[str]) -> dict:
    """Install the staged package into a fresh fixture repo and check the result."""
    if fixture.exists():
        shutil.rmtree(fixture)
    fixture.mkdir(parents=True)
    subprocess.run(["git", "init", "-q"], cwd=fixture, check=True)
    target_arg = ",".join(targets)
    steps = [_run_apm(apm_bin, ["install", str(staged_dir), "--target", target_arg, "--dry-run"], fixture),
             _run_apm(apm_bin, ["install", str(staged_dir), "--target", target_arg], fixture)]
    findings = [] if steps[-1]["exit_code"] == 0 else [
        _finding("error", "apm_install_failed", "", steps[-1]["output_tail"][-3:])]
    deployed_roots: list[str] = []
    if not findings:
        findings = _check_deployed_skills(fixture, staged_dir, skills)
        deployed_roots = sorted({p.relative_to(fixture).parts[0] for p in fixture.glob(".*/skills/*/SKILL.md")})
        steps.append(_run_apm(apm_bin, ["uninstall", f"_local/{staged_dir.name}"], fixture))
        leftovers = [s for s in skills if _deployed_skill_dirs(fixture, s)]
        if leftovers:
            findings.append(_finding("error", "uninstall_left_files", "", f"{len(leftovers)} skills still deployed"))
    return {"fixture": str(fixture), "steps": steps, "deployed_roots": deployed_roots,
            "passed": not any(f["level"] == "error" for f in findings), "findings": findings}


# Optional Stage 6: pack the staged package into an installable bundle (plan Section 10.3).
def pack_plugin(staged_dir: Path, dist_dir: Path, apm_bin: str) -> dict:
    """Run apm install (to write the lockfile) then apm pack --archive into dist_dir."""
    dist_dir.mkdir(parents=True, exist_ok=True)
    steps = [_run_apm(apm_bin, ["install"], staged_dir),
             _run_apm(apm_bin, ["pack", "--archive", "-o", str(dist_dir)], staged_dir)]
    bundles = sorted(str(b) for b in dist_dir.glob(f"{staged_dir.name}-*.zip"))
    passed = all(st["exit_code"] == 0 for st in steps) and bool(bundles)
    return {"steps": steps, "bundles": bundles, "passed": passed}


# ---------------------------------------------------------------------------
# Orchestration
# ---------------------------------------------------------------------------

# Run all five stages and write the JSON report.
def run_pipeline(args: argparse.Namespace) -> dict:
    """Execute inspect -> normalize -> validate -> package -> test deploy."""
    repo_root = Path(args.repo_root).resolve()
    plugin_dir = (repo_root / args.plugin).resolve()
    build_dir = (repo_root / args.build_dir).resolve()
    staged_dir = build_dir / plugin_dir.name
    targets = [t.strip() for t in args.targets.split(",") if t.strip()]

    report: dict = {"plugin": plugin_dir.name, "targets": targets}
    inspection = inspect_plugin(repo_root, plugin_dir)
    report["inspect"] = {k: v for k, v in inspection.items() if k != "symlinks"}
    report["inspect"]["symlink_count"] = len(inspection["symlinks"])
    report["normalize"] = normalize_plugin(inspection, staged_dir)
    report["validate"] = validate_package(staged_dir, report["normalize"])
    report["package"] = package_plugin(staged_dir, inspection, targets)
    if args.skip_deploy:
        report["test_deploy"] = {"skipped": True}
    else:
        fixture = (repo_root / args.deploy_dir).resolve() / plugin_dir.name
        report["test_deploy"] = run_test_deploy(staged_dir, fixture, targets, args.apm, inspection["skills"])
    if args.pack:
        report["pack"] = pack_plugin(staged_dir, (repo_root / args.dist_dir).resolve(), args.apm)
    report["passed"] = (report["validate"]["passed"] and report["test_deploy"].get("passed", True)
                        and report.get("pack", {}).get("passed", True))
    report_path = build_dir / f"{plugin_dir.name}.report.json"
    report_path.write_text(json.dumps(report, indent=2), encoding="utf-8")
    report["report_path"] = str(report_path)
    return report


# CLI entry point: parse arguments, run the pipeline, print a summary.
def main() -> None:
    """Parse CLI arguments and run the APM build pipeline for one plugin."""
    parser = argparse.ArgumentParser(description="Build-time APM packaging pipeline (plan Section 4)")
    parser.add_argument("--plugin", required=True, help="Plugin path relative to --repo-root, e.g. plugins/dev-utils")
    parser.add_argument("--repo-root", default=".", help="Git work tree root (default: .)")
    parser.add_argument("--build-dir", default="build/staging", help="Staging root (default: build/staging)")
    parser.add_argument("--deploy-dir", default="build/test-deploy", help="Fixture root (default: build/test-deploy)")
    parser.add_argument("--targets", default=",".join(DEFAULT_TARGETS), help="Comma-separated APM targets")
    parser.add_argument("--apm", default="apm", help="APM CLI executable (default: apm on PATH)")
    parser.add_argument("--skip-deploy", action="store_true", help="Skip Stage 5 (no APM needed)")
    parser.add_argument("--pack", action="store_true", help="Also pack an installable bundle (apm pack)")
    parser.add_argument("--dist-dir", default="build/dist", help="Bundle output root (default: build/dist)")
    args = parser.parse_args()

    report = run_pipeline(args)
    val, dep = report["validate"], report["test_deploy"]
    print(f"Plugin:     {report['plugin']}  ({len(report['inspect']['skills'])} skills, "
          f"{report['inspect']['symlink_count']} symlinks)")
    print(f"Staged:     {report['normalize']['staging_dir']}")
    print(f"Validate:   {'PASS' if val['passed'] else 'FAIL'} ({val['error_count']} errors)")
    for f in val["findings"][:20]:
        print(f"  [{f['level'].upper()}] {f['check']}: {f['path']} {f['detail']}")
        print(f"      fix: {f['fix']}" + (f"  ->  {f['suggestion']}" if f.get("suggestion") else ""))
    print(f"Test deploy: {'SKIPPED' if dep.get('skipped') else ('PASS' if dep['passed'] else 'FAIL')}")
    for f in dep.get("findings", [])[:20]:
        print(f"  [{f['level'].upper()}] {f['check']}: {f['path']} {f['detail']}")
    if "pack" in report:
        print(f"Pack:       {'PASS' if report['pack']['passed'] else 'FAIL'} {', '.join(report['pack']['bundles'])}")
    print(f"Report:     {report['report_path']}")
    sys.exit(0 if report["passed"] else 1)


if __name__ == "__main__":
    main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall