[FEATURE] Support plugin root bin/ for marketplace_plugin packages

[maro114510]

Is your feature request related to a problem? Please describe.

Yes. apm install deploys skills from marketplace_plugin packages, but it does not deploy or expose the package root bin/ directory.

This breaks skills that rely on helper executables shipped in bin/.

Example:

# ~/apm.yml
dependencies:
  apm:
    - owner/repo

apm install

Observed:

~/.claude/skills/example-skill/SKILL.md   ✓ deployed
~/.claude/skills/example-skill/bin/       ✗ not deployed
bin/example-helper.sh                     ✗ not on Bash tool PATH

Runtime failure:

Bash(example-helper.sh "some-argument")
Error: Exit code 127
(eval):1: command not found: example-helper.sh

Claude Code's plugin documentation defines bin/ as a plugin-root directory whose executables are added to the Bash tool's PATH while the plugin is enabled:

bin/ — Plugin root — Executables added to the Bash tool's PATH while the plugin is enabled.

So a plugin that works when installed via claude plugin install can fail when installed via apm install.

Describe the solution you'd like

For marketplace_plugin packages, apm should preserve the Claude Code plugin bin/ contract:

1. Deploy the package root bin/ directory.
2. Make the deployed bin/ available on the Bash tool's PATH.
3. Record the deployed bin/ path in apm.lock.yaml.

The exact on-disk location can follow apm's deployment model, but executables under plugin-root bin/ should be invokable as bare commands from Bash tool calls.

Describe alternatives you've considered

• Inline the script logic into SKILL.md, but this makes deterministic helper logic harder to test and maintain.
• Use a postinstall hook, but that adds security and complexity concerns.
• Symlink into ~/.local/bin, but that depends on apm cache/deployment internals.
• Call scripts by absolute path, but that makes skills apm-specific and diverges from Claude Code's plugin contract.

Additional context

apm.lock.yaml confirms that bin/ is currently absent from deployed_files:

- repo_url: owner/repo
  package_type: marketplace_plugin
  deployed_files:
  - .claude/skills/example-skill
  # no bin/ entry

This makes apm-managed marketplace_plugin packages less compatible with Claude Code's native plugin behavior.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/security
area/marketplace
area/distribution
type/feature
status/needs-design

Milestone

null

Suggested next action

Open a design doc (or discussion thread linked here) that answers: (1) the deployment path and PATH injection mechanism for bin/ per target, (2) the security/trust model for deployed binaries, (3) the apm.lock.yaml schema extension for bin/ entries, and (4) the cleanup contract on apm uninstall.

Suggested issue comment

Thanks for the thorough report, `@maro114510` -- the lockfile evidence and the Claude Code plugin-contract reference make the gap very concrete.

The capability gap is real: `apm install` does not honor the `bin/` contract that Claude Code defines for plugin-root directories, which means a plugin that works via `claude plugin install` can fail when deployed through APM. We want to close this gap.

However, deploying executables to the Bash tool's PATH is a significant supply-chain security surface, and we need to design this carefully before code lands. Specifically, we need to answer:

1. Where do the deployed binaries land on disk, and how is PATH modified per target (Claude vs Copilot vs other)?
2. What is the trust model -- can any `marketplace_plugin` package ship binaries, or does this require an explicit opt-in or policy flag?
3. How does `apm.lock.yaml` record the deployed `bin/` entries for reproducibility and cleanup?
4. What is the cleanup contract when running `apm uninstall`?

We are marking this `status/needs-design`. If you are interested in contributing, opening a design doc (or a detailed comment here) that proposes answers to the four questions above would be an excellent starting point. We will update this issue once the design is settled and implementation can begin.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The gap is real: Claude Code defines bin/ as a first-class plugin-root directory whose executables land on PATH, and APM does not honor this contract. The user's mental model is correct ("if claude plugin install puts binaries on PATH, apm install should too"). The deployed_files lockfile evidence is concrete. This is a legitimate capability gap that blocks marketplace_plugin packages that rely on helper executables.

Supply Chain Security Expert -- Risk-Surface Reviewer

Deploying executables to PATH is a significant supply-chain risk surface. A malicious package could ship binaries under bin/ that execute arbitrary code. The current Claude Code plugin install flow presumably includes trust/verification steps; APM must replicate or exceed that bar. At minimum, the design must address: prominent logging of deployed binaries, lockfile pinning for bin/ entries, and whether bin/ deployment requires explicit user opt-in or a policy flag. theme/security is the primary theme here; area/marketplace and area/distribution as sub-themes.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author has author_association: NONE -- first-time contributor. The issue is well-structured with concrete examples, lockfile evidence, and a reference to the Claude Code plugin spec. Comment validates the report quality, confirms the gap is accepted in principle, and invites the author to contribute a design doc with specific questions to answer.

Python Architect -- Architecture Reviewer

Fast-path triggered by proposed apm.lock.yaml schema change (new bin/ entries in deployed_files) and changes to the distribution/install pipeline. Cross-cutting design questions: where do binaries land per target, how is PATH modified, how does uninstall clean up? The implementation cannot land safely without answers to these questions. status/needs-design is the correct outcome.

Doc Writer -- Documentation Reviewer

Not activated -- status/needs-design outcome means no doc page is needed until the design is settled; doc work will be part of the implementing PR scope.

APM CEO -- Triage Arbiter

The feature request is legitimate and the gap is real, but deploying executables to PATH is the highest-risk surface in APM's distribution model. needs-design is the correct gate. theme/security wins over theme/portability given the binary-on-PATH risk -- the security design must be settled before the portability benefit can be realized. No milestone until design is complete.

{
  "decision": "needs-design",
  "decision_detail": "Design must answer: (1) binary deployment path and PATH injection mechanism per target, (2) security/trust model for deployed binaries, (3) apm.lock.yaml schema extension for bin/ entries, (4) cleanup contract on apm uninstall.",
  "theme": "theme/security",
  "areas": ["area/marketplace", "area/distribution"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Open a design doc or detailed comment answering the four design questions (deployment path, trust model, lockfile schema, uninstall cleanup) before implementation begins.",
  "comment_markdown": "Thanks for the thorough report, `@maro114510` -- the lockfile evidence and the Claude Code plugin-contract reference make the gap very concrete.\n\nThe capability gap is real: `apm install` does not honor the `bin/` contract that Claude Code defines for plugin-root directories, which means a plugin that works via `claude plugin install` can fail when deployed through APM. We want to close this gap.\n\nHowever, deploying executables to the Bash tool's PATH is a significant supply-chain security surface, and we need to design this carefully before code lands. Specifically, we need to answer:\n\n1. Where do the deployed binaries land on disk, and how is PATH modified per target (Claude vs Copilot vs other)?\n2. What is the trust model -- can any `marketplace_plugin` package ship binaries, or does this require an explicit opt-in or policy flag?\n3. How does `apm.lock.yaml` record the deployed `bin/` entries for reproducibility and cleanup?\n4. What is the cleanup contract when running `apm uninstall`?\n\nWe are marking this `status/needs-design`. If you are interested in contributing, opening a design doc (or a detailed comment here) that proposes answers to the four questions above would be an excellent starting point. We will update this issue once the design is settled and implementation can begin."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · sonnet46 2.6M · ◷

[maro114510]

Here are proposed answers to the four design questions raised in the triage decision.

---

Pre-implementation finding: Before settling on the design, I tested how Claude Code's bin/ PATH injection actually works. Three approaches were refuted empirically (placing files at ~/.claude/skills/<name>/bin/ without a manifest, writing arbitrary handles to enabledPlugins, and writing to installed_plugins.json + enabledPlugins). The confirmed mechanism is Claude Code's skills-dir feature: any ~/.claude/skills/<name>/ directory that contains a .claude-plugin/plugin.json manifest is auto-loaded as <name>@skills-dir at session start, and its bin/ is added to the Bash tool's PATH. No registry manipulation is required -- the manifest is the trigger. Verified with skills-dir-probe-ok in a live session.

---

1. Deployment path and PATH injection mechanism

Claude Code target only (v1). For user-scope installs, APM deploys:

• bin/<file> → ~/.claude/skills/<name>/bin/<file> (chmod 0o755 on POSIX)
• .claude-plugin/plugin.json → ~/.claude/skills/<name>/.claude-plugin/plugin.json

The manifest triggers Claude Code's skills-dir auto-load at the next session start, which adds ~/.claude/skills/<name>/bin/ to the Bash tool's PATH with no further APM action.

If the package ships only a root plugin.json (no .claude-plugin/ directory), APM synthesizes a minimal manifest containing only name and version. If either field is missing or malformed, bin/ deployment is skipped with a warning. If the manifest cannot be deployed due to a conflict with existing content at the target path, bin/ deployment is also skipped.

Non-Claude targets (Copilot, Cursor, etc.) have no equivalent bin/ PATH contract; this proposal defers them to per-target owners. Project-scope installs are deferred to v2 with a visible info log at install time.

2. Trust model

Auto-detect: if bin/ exists in a marketplace_plugin package, APM deploys it by default, matching claude plugin install behavior. No per-package producer opt-in flag is required (the filesystem convention is the declaration). Consumers who want to block deployment can do so via a new bin_deploy.deny key in apm-policy.yml:

bin_deploy:
  deny_all: false          # or true to block globally
  deny:
    - "owner/package-name"

This requires a supply-chain-security-expert review of the policy grammar extension, which is mandatory per CONTRIBUTING.md for any PR touching the supply chain.

3. apm.lock.yaml schema extension

No new top-level field is introduced. Deployed bin/ files and the plugin manifest are appended to the existing deployed_files list and deployed_file_hashes map:

- repo_url: https://github.com/owner/my-plugin
  package_type: marketplace_plugin
  deployed_files:
    - .claude/skills/my-plugin/SKILL.md
    - .claude/skills/my-plugin/.claude-plugin/plugin.json   # new
    - .claude/skills/my-plugin/bin/example-helper.sh        # new
  deployed_file_hashes:
    .claude/skills/my-plugin/SKILL.md: "sha256:abc..."
    .claude/skills/my-plugin/.claude-plugin/plugin.json: "sha256:xyz..."   # new
    .claude/skills/my-plugin/bin/example-helper.sh: "sha256:def..."        # new

4. Cleanup contract on apm uninstall

Standard: apm uninstall removes every path listed in deployed_files for that dependency. Because both bin/ files and the plugin manifest are recorded there, they are cleaned up by the existing uninstall path with no new logic. Removing the manifest causes Claude Code to stop loading the plugin as <name>@skills-dir from the next session.

If a bin/ file's on-disk hash does not match the lockfile (user-modified), that file is skipped with a warning and a manual cleanup instruction. If the .claude-plugin/ directory is nonempty after removing the manifest, it is left in place rather than force-deleted.

---

This proposal also introduces a normative behavior change that requires the OpenAPM v0.1 three-step ritual (spec anchor + manifest entry + @pytest.mark.req test) in the implementing PR.

Happy to revise any of the above before moving to implementation.