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

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

Purpose:
    Converts a plugin's file-level symlinks into copy-manifest entries (APM migration plan,
    Section 10.3; plugin architecture policy Section 5). For each symlink: the link is
    removed from the working tree and `symlinks.json` records the same pair with
    `strategy: "copy"`, so the build pipeline creates the physical copy in staging and the
    packed bundle carries it. The link is also untracked (`git rm --cached`), so the copy that
    materialize_copies.py later writes in its place stays out of git. Dry-run by default.

    Left alone (reported): symlinks under tests/ (tests run from source and are not packaged),
    and links whose target is missing, a directory, another symlink, or outside the plugin.
    Manifest entries with strategy "symlink" whose destination is now a real file are removed
    as stale.

Usage:
    python3 convert_symlinks_to_manifest.py --path <repo-root>                       # all plugins, dry-run
    python3 convert_symlinks_to_manifest.py --path <repo-root> --plugins dev-utils --apply

Exit codes: 0 success, 2 usage error.

Key Input Dependencies:
    - git (symlinks are read from the index, as in apm_build_pipeline.py)
    - <repo-root>/symlinks.json ({"version": ..., "links": [{src, dst, strategy, description}]})

Function Index:
    - plugin_links(root, plugin_rel) -> list[dict]
    - classify(root, plugin_rel, link) -> tuple[str, str]
    - update_manifest(links, converted, root) -> tuple[list, dict]
    - convert(root, plugins, apply) -> dict
    - main() -> None
"""

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

sys.path.insert(0, str(Path(__file__).resolve().parent))
from apm_build_pipeline import git_symlink_entries  # noqa: E402

SKIP_PARTS = ("/tests/",)


# All current symlinks of one plugin, from the git index.
def plugin_links(root: Path, plugin_rel: str) -> list[dict]:
    """Return [{path, link_text}] for the plugin's symlinks still present as links."""
    return git_symlink_entries(root, plugin_rel)


# Decide what to do with one link: convert it, or report why not.
def classify(root: Path, plugin_rel: str, link: dict) -> tuple[str, str]:
    """Return (action, detail): ('convert', target_rel) or ('skip', reason)."""
    if any(part in "/" + link["path"] for part in SKIP_PARTS):
        return "skip", "under tests/ (not packaged; tests run from source)"
    target = Path(os.path.normpath(root / Path(link["path"]).parent / link["link_text"]))
    target_rel = os.path.relpath(target, root).replace(os.sep, "/")
    if not target_rel.startswith(plugin_rel.rstrip("/") + "/"):
        return "skip", f"target outside the plugin: {target_rel}"
    if target.is_symlink():
        return "skip", f"target is itself a symlink: {target_rel}"
    if not target.is_file():
        return "skip", f"target missing or a directory: {target_rel}"
    return "convert", target_rel


# Merge converted pairs into the manifest; drop stale symlink entries.
def update_manifest(links: list, converted: list[dict], root: Path) -> tuple[list, dict]:
    """Return (new_links, stats). Existing entries for a dst are updated, not duplicated."""
    by_dst = {entry.get("dst"): entry for entry in links}
    stats = {"updated": 0, "added": 0, "stale_removed": 0}
    for pair in converted:
        entry = by_dst.get(pair["dst"])
        if entry:
            entry.update(src=pair["src"], strategy="copy")
            stats["updated"] += 1
        else:
            entry = {"src": pair["src"], "dst": pair["dst"], "strategy": "copy",
                     "description": "converted from symlink (APM migration)"}
            links.append(entry)
            by_dst[pair["dst"]] = entry
            stats["added"] += 1
    converted_dsts = {pair["dst"] for pair in converted}
    kept = []
    for entry in links:
        dst = root / entry.get("dst", "")
        stale = (entry.get("strategy") == "symlink" and entry.get("dst") not in converted_dsts
                 and dst.is_file() and not dst.is_symlink())
        if stale:
            stats["stale_removed"] += 1
        else:
            kept.append(entry)
    return kept, stats


# Convert the selected plugins; write changes only with apply=True.
def convert(root: Path, plugins: list[str], apply: bool) -> dict:
    """Return {converted, skipped, manifest} for the run."""
    converted, skipped = [], []
    for plugin in plugins:
        plugin_rel = f"plugins/{plugin}"
        for link in plugin_links(root, plugin_rel):
            action, detail = classify(root, plugin_rel, link)
            if action == "convert":
                converted.append({"src": detail, "dst": link["path"]})
            else:
                skipped.append({"path": link["path"], "reason": detail})
    manifest_path = root / "symlinks.json"
    data = json.loads(manifest_path.read_text(encoding="utf-8")) if manifest_path.is_file() else {"version": 1, "links": []}
    new_links, stats = update_manifest(data.get("links", []), converted, root)
    if apply:
        for pair in converted:
            (root / pair["dst"]).unlink()
        # Untrack the links so the materialized copies (materialize_copies.py) stay ignored.
        dsts = [pair["dst"] for pair in converted]
        for start in range(0, len(dsts), 500):
            subprocess.run(["git", "-C", str(root), "rm", "-q", "--cached", "--", *dsts[start:start + 500]], check=True)
        data["links"] = new_links
        manifest_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
    return {"applied": apply, "converted": converted, "skipped": skipped, "manifest": stats}


# CLI entry point.
def main() -> None:
    """Parse arguments, convert, print a summary."""
    parser = argparse.ArgumentParser(description="Convert plugin symlinks to copy-manifest entries")
    parser.add_argument("--path", default=".", help="Repository root (default: .)")
    parser.add_argument("--plugins", help="Comma-separated plugin names (default: every plugin)")
    parser.add_argument("--apply", action="store_true", help="Remove the links and write symlinks.json")
    args = parser.parse_args()
    root = Path(args.path).resolve()
    plugins = ([p.strip() for p in args.plugins.split(",") if p.strip()] if args.plugins
               else sorted(d.name for d in (root / "plugins").iterdir() if d.is_dir()))
    result = convert(root, plugins, args.apply)
    mode = "APPLIED" if args.apply else "DRY-RUN"
    print(f"{mode}: {len(result['converted'])} symlinks -> copy entries; manifest {result['manifest']}; "
          f"{len(result['skipped'])} skipped")
    for item in result["skipped"]:
        print(f"  [SKIP] {item['path']}: {item['reason']}")
    sys.exit(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