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/materialize_copies.py

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

Purpose:
    Writes every copy-manifest entry (`symlinks.json`, `strategy: "copy"`) into the working
    tree as a physical file, so the source checkout looks exactly like a built package: skill
    folders contain the files they use, tests and local runs work, and `apm install
    ./plugins/<plugin>` works locally. Git keeps only the canonical file: every materialized
    path is listed in the repository's local exclude file (`git rev-parse --git-path
    info/exclude`) between generated markers, so the copies are never committed.

    Run it after cloning and after changing a canonical file. `--check` reports copies that
    are missing or differ from their canonical source (edit the canonical file, never a copy)
    and exits 1 if any are found.

Usage:
    python3 materialize_copies.py --path <repo-root>           # write copies + exclude block
    python3 materialize_copies.py --path <repo-root> --check   # report drift only

Exit codes: 0 in sync / written, 1 drift found (--check) or a source is missing, 2 usage error.

Key Input Dependencies:
    - <repo-root>/symlinks.json (copy-manifest entries)
    - git (locates the local exclude file; works from a linked worktree)

Function Index:
    - copy_entries(root) -> list[dict]
    - exclude_path(root) -> Path
    - write_exclude_block(root, dsts) -> None
    - materialize(root, check) -> dict
    - main() -> None
"""

import argparse
import json
import shutil
import subprocess
import sys
from pathlib import Path

BEGIN = "# BEGIN copy-manifest materialized files (generated by materialize_copies.py)"
END = "# END copy-manifest materialized files"


# Copy-manifest entries from symlinks.json.
def copy_entries(root: Path) -> list[dict]:
    """Return [{src, dst}] for every entry with strategy "copy"."""
    manifest = root / "symlinks.json"
    if not manifest.is_file():
        return []
    links = json.loads(manifest.read_text(encoding="utf-8")).get("links", [])
    return [{"src": e["src"], "dst": e["dst"]} for e in links if e.get("strategy") == "copy"]


# The local exclude file git uses for this checkout (shared by linked worktrees).
def exclude_path(root: Path) -> Path:
    """Return the absolute path of info/exclude for the repository at root."""
    out = subprocess.run(["git", "-C", str(root), "rev-parse", "--git-path", "info/exclude"],
                         capture_output=True, text=True, check=True).stdout.strip()
    path = Path(out)
    return path if path.is_absolute() else (root / path)


# Replace the generated block in info/exclude with the current destinations.
def write_exclude_block(root: Path, dsts: list[str]) -> None:
    """Keep any hand-written exclude lines; regenerate only the marked block."""
    path = exclude_path(root)
    text = path.read_text(encoding="utf-8") if path.is_file() else ""
    if BEGIN in text and END in text:
        head, rest = text.split(BEGIN, 1)
        text = head.rstrip("\n") + "\n" + rest.split(END, 1)[1].lstrip("\n")
    block = "\n".join([BEGIN, *("/" + d for d in sorted(set(dsts))), END])
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(text.rstrip("\n") + ("\n\n" if text.strip() else "") + block + "\n", encoding="utf-8")


# Write (or with check=True, only compare) every copy; report what happened.
def materialize(root: Path, check: bool) -> dict:
    """Return {written, unchanged, drifted, missing_source} lists of destination paths."""
    result: dict = {"written": [], "unchanged": [], "drifted": [], "missing_source": []}
    entries = copy_entries(root)
    for entry in entries:
        src, dst = root / entry["src"], root / entry["dst"]
        if not src.is_file():
            result["missing_source"].append(entry["dst"])
            continue
        if dst.is_file() and not dst.is_symlink() and dst.read_bytes() == src.read_bytes():
            result["unchanged"].append(entry["dst"])
            continue
        if check:
            result["drifted"].append(entry["dst"])
            continue
        if dst.is_symlink() or dst.is_file():
            dst.unlink()
        dst.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy2(src, dst)
        result["written"].append(entry["dst"])
    if not check:
        write_exclude_block(root, [e["dst"] for e in entries])
    return result


# CLI entry point.
def main() -> None:
    """Parse arguments, materialize or check, print a summary."""
    parser = argparse.ArgumentParser(description="Materialize copy-manifest entries into the working tree")
    parser.add_argument("--path", default=".", help="Repository root (default: .)")
    parser.add_argument("--check", action="store_true", help="Report missing or drifted copies; write nothing")
    args = parser.parse_args()
    result = materialize(Path(args.path).resolve(), args.check)
    print(f"{'CHECK' if args.check else 'MATERIALIZE'}: written={len(result['written'])} "
          f"unchanged={len(result['unchanged'])} drifted={len(result['drifted'])} "
          f"missing_source={len(result['missing_source'])}")
    for dst in result["drifted"][:20]:
        print(f"  [DRIFT] {dst} differs from its canonical source (edit the canonical file)")
    for dst in result["missing_source"][:20]:
        print(f"  [MISSING SOURCE] {dst}")
    sys.exit(1 if result["drifted"] or result["missing_source"] else 0)


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