fix(install): MARKETPLACE_PLUGIN beats HOOK_PACKAGE in detection cascade (#780)

[danielmeppiel]

Summary

Closes #780.

apm install obra/superpowers (and any Claude Code plugin that ships both hooks/*.json AND agents/skills/commands/) was silently dropping skills, agents, and commands -- only the hook files made it onto disk. Root cause: the detect_package_type() cascade in src/apm_cli/models/validation.py checked the hook-only branch BEFORE the marketplace-plugin branch, and MARKETPLACE_PLUGIN's synthesizer (_map_plugin_artifacts) already maps hooks alongside agents/skills/commands -- so swapping the order means hooks still install, plus everything else.

What ships in this PR

This was reviewed by the apm-review-panel (architect, devx-ux, cli-logging, supply-chain, growth, CEO) and split into three deliverables. A and B ship here; C is queued as a follow-up issue.

A) Surgical detection fix

• Reorder the cascade so MARKETPLACE_PLUGIN is checked before HOOK_PACKAGE.
• Refactor: a new gather_detection_evidence() helper + DetectionEvidence dataclass so observability code can reuse the same scan without breaking the detect_package_type() public signature (PackageType, Optional[Path]).
• New _PLUGIN_DIRS = ("agents", "skills", "commands") constant -- canonical order, asserted by tests.

B) Observability (the bug was undebuggable)

The user reported "I see only hooks" because there was zero install-time signal of what APM thinks the package is. Three changes close that gap:

• Add HOOK_PACKAGE to the _format_package_type_label table -- it was missing entirely, so any hook-package classification was silent.
• Update the MARKETPLACE_PLUGIN label from "(plugin.json detected)" to "(plugin.json or agents/skills/commands)" -- matches the actual cascade behaviour.
• New CommandLogger.package_type_warn() at default visibility.
• New _warn_if_classification_near_miss() helper: when a package classifies as HOOK_PACKAGE but agents/, skills/, commands/, or .claude-plugin/ is also present, emit [!] Detected as Hook Package, but the package also contains: <dirs>. If you expected those primitives to install, the package may be missing a plugin.json -- please file an issue. This catches near-misses the order swap can't (e.g. .claude-plugin/ dir without plugin.json).
• Wired at both materialization sites (LocalDependencySource and the cached/fresh path).

C) Architectural refactor -- follow-up only

detect_package_type conflates evidence gathering, classification, and normalization-strategy selection into a single positional-priority cascade. The next bundled format will create the next ordering bug. The clean separation is FormatDetector interface + PackageFormatRegistry + NormalizationPlanner. Filing as a separate issue post-merge -- too risky to bundle with the P1 fix.

Why the order swap is safe

MARKETPLACE_PLUGIN triggers normalize_plugin_directory() -> synthesize_apm_yml_from_plugin -> _map_plugin_artifacts (src/apm_cli/deps/plugin_parser.py:481-511). _map_plugin_artifacts explicitly handles hooks (inline dict, config file path, OR directory). So MARKETPLACE_PLUGIN is a strict superset of HOOK_PACKAGE's capabilities -- nothing is lost by moving plugin classification ahead of the hook-only branch.

Supply-chain check (panel): no security regression -- the synthesizer already does path-safety via _is_within_plugin. The new near-miss warning is itself a mild integrity signal: a plugin missing parts of itself is worth surfacing.

Tests

• tests/test_apm_package_models.py::TestDetectPackageType -- 3 new regression tests:
  • test_marketplace_plugin_wins_over_hooks_via_agents_dir
  • test_marketplace_plugin_wins_over_hooks_via_plugin_json
  • test_obra_superpowers_layout (full-fidelity reproducer)
• tests/test_apm_package_models.py::TestGatherDetectionEvidence -- 3 tests for the new helper.
• tests/unit/install/test_sources_classification.py -- 9 tests covering the label table (asserts every classifiable PackageType has a label, catches future silent-classification regressions) and the near-miss warning behaviour.

Full unit suite: 4180 passed (1 pre-existing unrelated mock failure deselected).

Manual verification plan

# Pre-fix repro:
apm install obra/superpowers
# -> reports only Hooks 2

# Post-fix expected:
apm install obra/superpowers
# -> reports Skills 8+, Agents 1, Commands 3+, Hooks 2
# -> with -v: "Package type: Marketplace Plugin (plugin.json or agents/skills/commands)"

Files changed

• src/apm_cli/models/validation.py -- cascade reorder + evidence helper.
• src/apm_cli/install/sources.py -- label centralisation + near-miss warning + wiring.
• src/apm_cli/core/command_logger.py -- package_type_warn() method.
• tests/test_apm_package_models.py -- 6 new tests.
• tests/unit/install/test_sources_classification.py -- new file, 9 tests.
• CHANGELOG.md -- Fixed entry.

[danielmeppiel]

Architectural follow-up filed as #782 (Visitor / Format-Discovery refactor) -- not blocking this PR.

[Copilot]

Pull request overview

Fixes a misclassification bug where Claude marketplace plugins that also ship hooks/*.json were detected as hook-only packages (dropping skills/agents/commands), and adds a new strict-by-default SSH/HTTPS transport-selection engine (with CLI/env controls) plus observability improvements around both behaviors.

Changes:

• Reorders package-type detection (MARKETPLACE_PLUGIN before HOOK_PACKAGE) and adds reusable detection evidence gathering + near-miss warnings.
• Introduces strict-by-default git transport selection (SSH vs HTTPS), with --ssh/--https, APM_GIT_PROTOCOL, and an escape-hatch --allow-protocol-fallback / APM_ALLOW_PROTOCOL_FALLBACK.
• Adds unit/integration tests and updates docs + changelog entries for the new behaviors.

Show a summary per file

File	Description
src/apm_cli/models/validation.py	Adds DetectionEvidence + gather_detection_evidence() and reorders detection cascade to prefer marketplace plugins over hook-only packages.
src/apm_cli/install/sources.py	Centralizes package-type labels and adds hook-classification near-miss warnings during materialization.
src/apm_cli/core/command_logger.py	Adds package_type_warn() for default-visibility warnings.
src/apm_cli/models/dependency/reference.py	Records explicit_scheme on parsed dependency refs to drive strict transport selection.
src/apm_cli/deps/transport_selection.py	New pure transport selection engine + insteadOf resolver + env helpers.
src/apm_cli/deps/github_downloader.py	Uses TransportSelector for clone attempt planning; makes clone env decision per-attempt.
src/apm_cli/commands/install.py	Adds --ssh, --https, --allow-protocol-fallback and plumbs into install pipeline.
src/apm_cli/install/context.py	Carries protocol_pref and allow_protocol_fallback through the pipeline.
src/apm_cli/install/request.py	Adds transport-selection fields to InstallRequest.
src/apm_cli/install/service.py	Passes transport-selection fields into pipeline entrypoint.
src/apm_cli/install/pipeline.py	Plumbs transport-selection fields into InstallContext.
src/apm_cli/install/phases/resolve.py	Instantiates downloader with protocol preference + fallback policy.
tests/test_apm_package_models.py	Adds regression tests for #780 and tests for gather_detection_evidence().
tests/unit/install/test_sources_classification.py	Adds tests for label coverage and near-miss warning behavior.
tests/unit/test_auth_scoping.py	Updates auth-scoping tests for strict transport + per-attempt env behavior.
tests/unit/test_transport_selection.py	New unit test matrix for transport-selection decisions and caching.
tests/integration/test_transport_selection_integration.py	New network-gated integration tests validating attempted clone URLs end-to-end.
tests/fixtures/gitconfig_insteadof_to_ssh	Fixture .gitconfig enabling an insteadOf rewrite to SSH.
scripts/test-integration.sh	Runs the new transport selection integration tests as part of e2e script.
docs/src/content/docs/reference/cli-commands.md	Documents new apm install flags and env vars.
docs/src/content/docs/guides/dependencies.md	Documents strict transport selection contract + fallback escape hatch.
docs/src/content/docs/getting-started/authentication.md	Updates troubleshooting and adds “Choosing transport” guidance.
packages/apm-guide/.apm/skills/apm-usage/dependencies.md	Updates apm-guide dependency docs with transport selection section.
CHANGELOG.md	Adds Unreleased entries for strict transport selection + #780 fix.

Copilot's findings

Comments suppressed due to low confidence (1)

CHANGELOG.md:18

• The new Unreleased changelog entries end with (#778), but this change is landing in PR #780. Per the project changelog convention, each entry should end with the current PR number, and related items should be collapsed to a single line per PR under the appropriate section.

### Changed (BREAKING)

- Strict-by-default transport selection: explicit `ssh://`/`https://` URLs no longer silently fall back to the other protocol; shorthand consults `git config url.<base>.insteadOf` and otherwise defaults to HTTPS. Set `APM_ALLOW_PROTOCOL_FALLBACK=1` (or pass `--allow-protocol-fallback`) to restore the legacy permissive chain; cross-protocol retries then emit a `[!]` warning. Closes #328 (#778)

### Added

- `apm install --ssh` / `--https` flags and `APM_GIT_PROTOCOL=ssh|https` env to pick the initial transport for shorthand dependencies (#778)
- `apm install --allow-protocol-fallback` flag and `APM_ALLOW_PROTOCOL_FALLBACK=1` env as the migration escape hatch for cross-protocol fallback (#778)

• Files reviewed: 6/6 changed files
• Comments generated: 1

[danielmeppiel]

Manual repro on the real obra/superpowers repo

Cloned the actual repo (git clone https://github.com/obra/superpowers.git, v5.0.7) and verified the fix end-to-end against the production layout, not just the synthetic fixture.

Before fix: classified as hook_package -> only hooks installed.

After fix:

PackageType: marketplace_plugin
plugin.json: /tmp/superpowers/.claude-plugin/plugin.json

Evidence:
  has_apm_yml:        False
  has_skill_md:       False
  has_hook_json:      True
  plugin_json_path:   /tmp/superpowers/.claude-plugin/plugin.json
  plugin_dirs_present: ('agents', 'skills', 'commands')
  has_plugin_evidence: True

Then ran normalize_plugin_directory() on it -- the synthesizer correctly populated .apm/ with everything that was being silently dropped pre-fix:

.apm/agents/code-reviewer.md            [+] 1 agent
.apm/skills/                             [+] 11 skills (TDD, systematic-debugging,
                                              dispatching-parallel-agents,
                                              executing-plans, brainstorming,
                                              receiving-code-review,
                                              requesting-code-review,
                                              subagent-driven-development,
                                              using-git-worktrees,
                                              using-superpowers,
                                              finishing-a-development-branch)
.apm/prompts/                            [+] 3 commands (brainstorm, execute-plan,
                                              write-plan)
.apm/hooks/                              [+] hooks.json + hooks-cursor.json
                                              (still installed, not regressed)

All primitives now flow through the integration pipeline. Hooks are not regressed.