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

View on GitHub
#!/usr/bin/env python
"""
check_for_broken_symlinks.py
=====================================

Purpose:
    Scans all files and symlinks across plugins and builds an inventory database,
    detecting broken symlinks and generating corrective mapping repair scripts.

Layer: Investigate / Codify

Usage:
    pythoncheck_for_broken_symlinks.py

Key Input Dependencies:
    - plugins/ directory tree (files and symlinks)
    - os, json (standard library)
"""

import os
import json
from typing import List, Dict, Tuple, Any

PROJECT_ROOT: str = os.getcwd()
PLUGINS_DIR: str = os.path.join(PROJECT_ROOT, "plugins")

def build_inventory(plugins_dir: str) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
    """
    Scans the plugins folder and builds file and symlink inventory lists.

    Args:
        plugins_dir: Absolute path to the plugins directory.

    Returns:
        A tuple containing (inventory, symlinks) lists.
    """
    inventory_list: List[Dict[str, Any]] = []
    symlinks_list: List[Dict[str, Any]] = []

    for root, dirs, files in os.walk(plugins_dir):
        for name in files + dirs:
            if name.startswith("."):
                continue
                
            full_path = os.path.join(root, name)
            rel_path = os.path.relpath(full_path, PROJECT_ROOT)
            is_link = os.path.islink(full_path)
            
            entry = {
                "name": name,
                "path": rel_path,
                "is_symlink": is_link
            }
            
            if is_link:
                target = os.readlink(full_path)
                entry["target"] = target
                entry["is_broken"] = not os.path.exists(full_path)
                symlinks_list.append(entry)
            
            inventory_list.append(entry)
            
    return inventory_list, symlinks_list

def _index_physical_files(inventory_list: List[Dict[str, Any]]) -> Dict[str, List[str]]:
    """Build a name -> [paths] index of all non-symlink, non-directory files."""
    physical_files_by_name: Dict[str, List[str]] = {}
    for item in inventory_list:
        if not item["is_symlink"] and not os.path.isdir(os.path.join(PROJECT_ROOT, item["path"])):
            name = item["name"]
            if name not in physical_files_by_name:
                physical_files_by_name[name] = []
            physical_files_by_name[name].append(item["path"])
    return physical_files_by_name

def _resolve_broken_link(link: Dict[str, Any], physical_files_by_name: Dict[str, List[str]]) -> Tuple[str, str]:
    """Attempt to find a correct-target candidate and repair command for one broken symlink."""
    name = link["name"]
    loc = link["path"]

    candidates = physical_files_by_name.get(name, [])
    mapped = "⚠️  Unknown target"
    fix_cmd = ""

    link_parts = loc.split("/")
    if "skills" in link_parts and "references" in link_parts:
         skill_name = link_parts[link_parts.index("skills") + 1]
         for cand in candidates:
             if f"skills/{skill_name}/{name}" in cand:
                  mapped = f"`../{name}` (Skill Root)"
                  fix_cmd = f"ln -f -s '../{name}' '{loc}'"
                  break

    if fix_cmd == "" and candidates:
         plugin_name = link_parts[1]
         for cand in candidates:
             if cand.startswith(f"plugins/{plugin_name}/references/{name}"):
                  mapped = f"`../../../references/{name}` (Plugin References)"
                  fix_cmd = f"ln -f -s '../../../references/{name}' '{loc}'"
                  break

    if fix_cmd == "" and candidates:
         for cand in candidates:
             if "assets/" in cand:
                  mapped = f"Found elsewhere: {cand}"
                  break

    return mapped, fix_cmd

def perform_gap_analysis(
    inventory_list: List[Dict[str, Any]],
    symlinks_list: List[Dict[str, Any]]
) -> Tuple[List[str], List[str]]:
    """
    Compares broken symlinks against physical file paths to map targets.

    Args:
        inventory_list: List of all files and directories.
        symlinks_list: List of all symbolic links found.

    Returns:
        A tuple containing (report_lines, fix_commands) lists.
    """
    physical_files_by_name = _index_physical_files(inventory_list)

    report_lines = [
        "# Broken Symlinks Repair Report",
        "",
        "| Current Symlink Location | Target points to | Correct Target Candidate | Status |",
        "|--------------------------|------------------|--------------------------|--------|",
    ]
    fix_commands = ["#!/bin/bash", "echo 'Repairing symlinks...'"]

    for link in symlinks_list:
        if link.get("is_broken", False):
            loc = link["path"]
            target = link["target"]

            mapped, fix_cmd = _resolve_broken_link(link, physical_files_by_name)

            if fix_cmd != "":
                 report_lines.append(f"| `{loc}` | `{target}` | {mapped} | ✅ Fixable |")
                 fix_commands.append(f"ln -f -s '{mapped.split('`')[1]}' '{loc}'" if mapped.startswith("`") else fix_cmd)
            else:
                 report_lines.append(f"| `{loc}` | `{target}` | {mapped} | ⚠️  Manual Fix |")

    return report_lines, fix_commands

def save_outputs(inventory_list: List[Dict[str, Any]], report_lines: List[str], fix_commands: List[str]) -> None:
    """
    Saves the JSON inventory, Markdown report, and shell script file representations.

    Args:
        inventory_list: List of full filesystem inventory dictionary items.
        report_lines: Formatted markdown strings.
        fix_commands: Corrective bash shell scripts.
    """
    inventory_path = os.path.join(PLUGINS_DIR, "agent-scaffolders/references/plugin_files_and_symlinks_inventory.json")
    os.makedirs(os.path.dirname(inventory_path), exist_ok=True)
    with open(inventory_path, "w") as f:
        json.dump(inventory_list, f, indent=2)

    report_path = os.path.join(PLUGINS_DIR, "agent-scaffolders/references/broken_symlinks_repair_report.md")
    with open(report_path, "w") as f:
        f.write("\n".join(report_lines))

    fix_script_path = os.path.join(PLUGINS_DIR, "agent-scaffolders/scripts/apply_symlink_repairs.sh")
    with open(fix_script_path, "w") as f:
        f.write("\n".join(fix_commands))

    print("✅ Analysis Complete.")
    print(f"Report: {report_path}")
    print(f"Fix Script: {fix_script_path}")

def main() -> None:
    """Main execution orchestrator."""
    print("Scanning plugins for all files and symlinks...")
    inv_list, sym_list = build_inventory(PLUGINS_DIR)
    
    rep_lines, fix_cmds = perform_gap_analysis(inv_list, sym_list)
    
    save_outputs(inv_list, rep_lines, fix_cmds)

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