Repository navigation
feat(marketplace): select a catalog in a repo with marketplace add --path - #3628
Conversation
Register several catalogs from one repository: --path selects a repository-relative marketplace JSON (contained, no traversal), skips auto-discovery, and is recorded in the registration so browse, search, update and install read the same catalog. Mirrors Claude Code's path field on github/git marketplace sources. Admission is owned by marketplace/source_identity.py and also guards persisted reloads. Docs: CLI reference, consumer guide, per-audience producer recipe, discovery order, and the access-control caveat. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…319-multi-marketplace-catalogs
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
Unescaped path characters can alter GitHub/GHES requests and override the selected ref, while a non-string persisted path can abort loading the entire registry.
2 open issues
What changed in this PR
Adds apm marketplace add --path so one repository can expose separate catalogs for different audiences, using the existing marketplace registration and fetch flows.
Changes:
- Adds explicit catalog selection while preserving default discovery when
--pathis omitted. - Validates and persists catalog paths for reuse by browsing, searching, refreshing, and installation.
- Adds regression coverage and documents per-audience catalogs, discovery order, and access-control limitations.
| File | Description |
|---|---|
tests/unit/marketplace/test_marketplace_catalog_path.py |
Tests path admission, persistence, CLI errors, and refresh. |
tests/integration/test_marketplace_catalog_path_lifecycle.py |
Exercises two catalogs through registration, refresh, and installation. |
tests/integration/test_architecture_marketplace_source_admission.py |
Tests enforcement of shared path admission. |
src/apm_cli/marketplace/source_identity.py |
Adds catalog-path validation and normalization. |
src/apm_cli/marketplace/models.py |
Validates persisted catalog paths during construction. |
src/apm_cli/commands/marketplace/__init__.py |
Adds --path, explicit fetching, and diagnostics. |
scripts/architecture_linter/checks/marketplace_bundle_and_audit.py |
Requires command and model routing through path admission. |
packages/apm-guide/.apm/skills/apm-usage/commands.md |
Documents the option in CLI usage guidance. |
docs/src/content/docs/reference/cli/marketplace.md |
Explains path selection, persistence, and discovery order. |
docs/src/content/docs/producer/publish-to-a-marketplace.md |
Adds a per-audience catalog publishing recipe. |
docs/src/content/docs/consumer/installing-from-marketplaces.md |
Shows registration of multiple catalogs from one repository. |
CHANGELOG.md |
Records the new catalog-selection feature. |
.apm/architecture/owners/marketplace-plugins.json |
Extends source-admission ownership to catalog paths. |
Review effort: Balanced
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 1 | 1 | Catalog-path admission correctly extends single-owner gate with dual guardrail; harden gate to also reject URL-significant chars. |
| DevX UX Expert | 0 | 1 | 1 | Solid flag design, help, errors; recommend guarding silent overwrite when --path reuses the same derived name. |
| Supply Chain Security Expert | 0 | 0 | 1 | Admission is thorough; two planned folds (non-string ValueError, quote in _github_contents_url) are necessary and sufficient. One defense-in-depth nit. |
| Doc Writer | 0 | 1 | 2 | Docs match the code and cover the full approved scope (option, recipe, discovery order, access caveat, apm-usage guide), all ASCII. Consumer guide repeats reference text; trim it. |
| Test Coverage Expert | 0 | 0 | 0 | All five Done-when scenarios map to tests at unit+lifecycle tiers; admission has 13 rejection vectors; path persists through refresh/update/install; ship. |
| Performance Expert | 0 | 0 | 1 | --path eliminates up to 2 wasted discovery probes (3 RTT -> 1 RTT on add); admission guard in post_init adds ~2us/source on registry load -- noise. Ship. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 5 follow-ups
- [Python Architect] Reject '?' and '#' in admit_marketplace_catalog_path as defense-in-depth alongside the Copilot quote() fold. -- Both python-architect and supply-chain-security-expert converged on this. The admission gate should own the full path-validity contract for all downstream consumers.
- [DevX UX Expert] Warn (do not silently overwrite) when a --path registration resolves to a name that already exists with a different url or path. -- The primary --path use case is multiple catalogs from one repo; a silent replace is found only on a failed install. A one-line warning with a --name hint removes the footgun.
- [Doc Writer] Trim consumer guide duplication: replace restated discovery-order and path-rules text with a link to the CLI reference. -- One source of truth prevents drift on future changes.
- [Doc Writer] Error message for missing catalog should name the user's --path value, not a generic 'No marketplace.json found'. -- --path accepts any .json file name; the current message is misleading for non-default names.
- [DevX UX Expert] Move the Claude Code interop note out of the --path flag table into the prose section below. -- Tool-specific jargon in the flag table confuses non-Claude users.
Architecture
classDiagram
direction LR
class MarketplaceSource {
<<ValueObject>>
+name str
+url str
+ref str
+path str
+__post_init__()
}
class SourceAdmission {
<<CanonicalOwner>>
+parse_marketplace_source(src, host_flag) Identity
+admit_marketplace_catalog_path(path) str
}
class MarketplaceClient {
<<IOBoundary>>
+_fetch_file(source, file_path) dict
+_auto_detect_path_with_payload(source) tuple
}
class MarketplaceRegistry {
<<IOBoundary>>
+add_marketplace(source) None
+_load() list
}
class ArchLinter {
<<StaticGuard>>
+_check_marketplace_source_admission()
}
class PathSecurity {
<<Pure>>
+validate_path_segments(path_str) None
}
MarketplaceSource ..> SourceAdmission : __post_init__ delegates
SourceAdmission ..> PathSecurity : catalog path uses
MarketplaceClient ..> MarketplaceSource : reads
MarketplaceRegistry *-- MarketplaceSource : persists
ArchLinter ..> SourceAdmission : guards single-owner
class MarketplaceSource:::touched
class SourceAdmission:::touched
class ArchLinter:::touched
classDef touched fill:#fff3b0,stroke:#d47600
flowchart TD
CLI["apm marketplace add SOURCE --path P"] --> PARSE["parse_marketplace_source"]
PARSE --> PATH_Q{"--path given?"}
PATH_Q -- no --> AUTO["_auto_detect_path_with_payload: root, .github/plugin/, .claude-plugin/"]
PATH_Q -- yes --> DIRECT{"hosted URL or local file SOURCE?"}
DIRECT -- yes --> ERR1["exit 1: --path not supported"]
DIRECT -- no --> ADMIT["admit_marketplace_catalog_path"]
ADMIT -- ValueError --> ERR2["exit 1: Invalid --path with hint"]
ADMIT -- ok --> FETCH["_fetch_file at PATH only"]
FETCH -- None --> ERR3["exit 1: no catalog at path"]
FETCH -- found --> BUILD["MarketplaceSource path re-admitted in __post_init__"]
AUTO --> BUILD
BUILD --> SAVE["registry.add_marketplace"]
SAVE --> USE["browse / search / update / install read saved path"]
Recommendation
Ship after the merge worker folds the two planned Copilot items (non-string ValueError, quote() in _github_contents_url) and the converged '?'/'#' admission rejection. The silent-overwrite warning (devx-ux-expert) and docs trim (doc-writer) are valuable but do not need to gate this PR. Test coverage is comprehensive, architecture is clean, and the feature closes the accepted issue scope.
Full per-persona findings
Python Architect
- [recommended] admit_marketplace_catalog_path should reject ? and # at the gate as defense-in-depth at
src/apm_cli/marketplace/source_identity.py:109
A path like catalogs/marketplace.json?ref=evil#frag.json passes all current admission checks. Downstream fetchers build URLs differently: _github_contents_url interpolates file_path unencoded (Copilot fold adds quote -- correct), GitLab already quotes. Per single-owner discipline the admission gate should own the full path-validity contract for ALL consumers rather than relying on each to quote. These characters are never legitimate in a repository-relative catalog path.
Suggested: After the backslash check, raise ValueError when '?' or '#' is present; add a parametrize case to test_rejects_escaping_or_malformed_paths. - [nit] Design patterns: well-applied ValueObject and single canonical owner; no further abstraction needed
MarketplaceSource is a frozen value object enforcing invariants via the canonical admission owner; admit_marketplace_catalog_path is the sole authority for catalog path validity, called from CLI input and persisted reload, guarded by static linter plus behavioral test. Current shape is the simplest correct design at this scope.
DevX UX Expert
- [recommended] Silent overwrite when --path is used twice on the same repo without --name and manifest names collide. at
src/apm_cli/commands/marketplace/__init__.py:580
add_marketplace replaces any existing entry with the same case-insensitive name. Without --name the name is derived from manifest.name or the repo URL tail. The primary --path use case is several catalogs from one repo; if two catalogs share a manifest name (or lack one), the second add silently replaces the first. The user learns only when an install from the first catalog fails.
Suggested: When an entry with the resolved name exists and the new registration has a different url or path, warn: Replacing existing marketplace (was: ). Use --name to keep both registrations.
Proof (missing at):tests/unit/marketplace/test_marketplace_catalog_path.py-- proves: Two --path adds to the same repo with colliding derived names warn instead of silently overwriting the first registration. - [nit] Claude Code reference in the --path flag table is tool-specific jargon in user-facing reference docs. at
docs/src/content/docs/reference/cli/marketplace.md:123
Useful as a design note but confusing for non-Claude users in the flag table; CLI help already omits it.
Suggested: Move the interop note into the prose below the table.
Supply Chain Security Expert
- [nit] Reject URL metacharacters ? and # at the admission layer for defense-in-depth at
src/apm_cli/marketplace/source_identity.py:103
admit_marketplace_catalog_path admits paths containing ? and #. A path like marketplace.json?ref=evil#x.json passes all current checks. The planned quote(file_path, safe='/') fold neutralises these for the GitHub URL builder, and GitLab/ADO builders already encode. However, ? and # have no legitimate use in a repository-relative JSON file path, and any future URL builder that interpolates file_path without encoding would reintroduce the injection.
Suggested: After the backslash check, reject '?' and '#' with ValueError.
Doc Writer
- [recommended] Consumer guide restates discovery order, path rules and the access caveat that the CLI reference already defines at
docs/src/content/docs/consumer/installing-from-marketplaces.md:250
The consumer paragraph repeats the discovery list, the fail-before-registering rule and the access caveat almost word for word from reference/cli/marketplace.md. Repo doc rules say to state a fact once and link to it everywhere else; each extra copy can drift.
Suggested: Keep the two-command example, the saved-and-reused sentence and the access caveat; replace the discovery-order and path-rules sentences with one link to the marketplace add --path reference. - [nit] Missing-file error says 'No marketplace.json found' even when --path names a differently named file at
src/apm_cli/commands/marketplace/__init__.py:501
--path accepts any .json file name (e.g. catalogs/frontend/catalog.json); the error should name what the user passed.
Suggested: No marketplace catalog found at '' ... - [nit] Reference discovery paragraph is wordy and repeats itself at
docs/src/content/docs/reference/cli/marketplace.md:129
Two stacked qualifiers and a repeated 'first one wins' sentence; repo voice rules call for short, direct text.
Suggested: Without --path, APM checks marketplace.json, .github/plugin/marketplace.json, then .claude-plugin/marketplace.json, and registers the first one found. Drop the 'If several exist' sentence.
Test Coverage Expert
No findings.
Performance Expert
- [nit] admit_marketplace_catalog_path rescans self.path on every MarketplaceSource construction including registry loads at
src/apm_cli/marketplace/models.py:205
Pure CPU string work, about 1-2us per source, under 0.5% of registry load wall-time; the in-process _registry_cache bounds it to one pass per command. Acceptable for the correctness gain of rejecting hand-edited traversal on reload.
Suggested: No action needed.
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.
A persisted non-string path raised AttributeError and aborted the whole registry load, and a path carrying '?' or '#' could change the file or ref the GitHub Contents API request names. Admission now rejects non-string paths and URL query/fragment characters with ValueError (so registry load skips the entry), and _github_contents_url percent-encodes the file path. Addresses Copilot inline on src/apm_cli/marketplace/source_identity.py:103 and :117, and panel follow-up FU-1 (python-architect, supply-chain). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Registering several catalogs from one repository is the main --path use case; a second add under a name already bound to a different catalog silently replaced it. Warn with the replaced source and path and suggest --name. Registrations without --path keep their silent replace. The missing-file error now names the catalog the user passed rather than a fixed marketplace.json. Regression tests cover both, plus the admission and URL-encoding fixes. Addresses panel follow-ups FU-2 (devx-ux-expert) and FU-4 (doc-writer). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The consumer guide restated the discovery order and path rules from the CLI reference; link to the reference instead. Tighten the reference discovery paragraph, move the Claude Code note out of the flag table, and document the '?'/'#' rule and the replace warning. Addresses panel follow-ups FU-3 (doc-writer) and FU-5 (devx-ux-expert). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
test_marketplace_source_admission_has_single_owner checked only the URL parser, so unrouting admit_marketplace_catalog_path from the model left it green. Assert the single owner definition and both consumer calls so the architecture test and the static guard fail together on that mutation. Canonical-owner gate: dual-guardrail architecture assertion for the marketplace-source-admission owner extension. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Delta panel follow-ups. _github_raw_contents_url (plugin apm.yml fetch for marketplace audit) still interpolated file_path raw, unlike the fixed catalog builder; encode it the same way. Pin the replace-warning cross-case (a bare re-add over a --path registration warns, because it drops a chosen catalog) and extend the real-CLI rejection sequence with a '#' path so the URL-metacharacter guard is proven end to end. Addresses delta follow-ups from supply-chain-security-expert, devx-ux-expert and test-coverage-expert. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| PR | head SHA | CEO stance | iters | folds | defers | Copilot rounds | CI | mergeable | mergeStateStatus | notes |
|---|---|---|---|---|---|---|---|---|---|---|
| #3628 | 021f236 |
ship_now | 2 | 11 | 0 | 2 | green | MERGEABLE | BLOCKED | pending required review |
Convergence
2 outer iteration(s); 2 Copilot round(s). Final panel stance: ship_now. Scope: delivers the full apm-scope:v1 record on #3319 (PR body carries Fixes #3319). Ready for maintainer review.
Panel summary
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 0 | 0 | FU-1 correctly hardened: ?/# rejection, non-string guard and URL encoding route through the admit_marketplace_catalog_path single owner; _warn_if_replacing_catalog is command-layer UX, not a second authority. |
| DevX UX Expert | 0 | 1 | 0 | FU-2 and FU-5 closed; replace-warning cross-case (existing custom path, new bare add) needs a test to document intent. |
| Supply Chain Security Expert | 0 | 1 | 0 | Admission and encoding fixes are correct; no regression on existing fetch paths. Sibling _github_raw_contents_url still interpolated file_path unencoded. |
| Doc Writer | 0 | 0 | 0 | FU-3 and FU-4 are closed. Docs match the new ?/# rejection, the replace warning and the new error text, and the consumer-guide link resolves. |
| Test Coverage Expert | 0 | 1 | 0 | All delta behaviors have regression traps; the ?/# guard should also be proven through the real CLI rejection sequence. |
| Performance Expert | 0 | 0 | 0 | Delta adds microseconds of CPU (quote, isinstance, cached registry scan) to a network-bound CLI command; no hot-path regression. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Recommendation
Every finding from both advisory rounds -- five original follow-ups plus three delta items -- has been folded with mutation-break-proven regression tests. Docs, lint, and architecture assertions are current at the final head. No remaining follow-ups. Ready for maintainer merge.
Full per-persona findings
Python Architect
No findings.
DevX UX Expert
- [recommended] Replace warning also fires on a bare re-add over a --path registration; untested at
src/apm_cli/commands/marketplace/__init__.py:679
The condition explicit_path or existing.path != source.path warns when a no-path add replaces an entry that had a custom path. Arguably better UX (warns before losing a chosen catalog), and such entries only exist because of --path, but only the both-default case is tested.
Suggested: Add a cross-case test asserting the warning fires.
Proof (missing at):tests/unit/marketplace/test_marketplace_catalog_path.py-- proves: A bare re-add over a --path registration warns before dropping the chosen catalog.
Supply Chain Security Expert
- [recommended] _github_raw_contents_url (audit path) does not percent-encode file_path, unlike the now-fixed _github_contents_url at
src/apm_cli/marketplace/client.py:1067
The sibling builder used by fetch_raw for marketplace audit plugin apm.yml fetches interpolated file_path raw. Its input is traversal-checked but not '?'/'#'-checked, so a malicious catalog could inject query parameters into the audit Contents API request. Pre-existing and low incremental risk, but inconsistent with the fixed sibling.
Suggested: encoded_path = quote(file_path, safe='/') as in _github_contents_url.
Doc Writer
No findings.
Test Coverage Expert
- [recommended] ?/# path guard has a unit regression trap but no real-binary test at
tests/integration/test_marketplace_catalog_path_lifecycle.py
'?' or '#' in a catalog path could alter the Contents API request, a secure-by-default surface with an integration-with-fixtures floor. The lifecycle test already has a rejection run_sequence; one more tuple proves it end to end.
Suggested: Add ('marketplace','add',_REMOTE,'--ref','main','--path','catalogs/a#b.json') with returncode 1 and assert the Invalid --path message.
Proof (missing at):tests/integration/test_marketplace_catalog_path_lifecycle.py-- proves: A catalog path containing ? or # is rejected by the real CLI before any request.
Performance Expert
No findings.
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.
…alogs Resolve conflicts with #3367 (live local apm.yml catalogs, --offline): - marketplace add: keep both --path (catalog_path) and --offline params and both docstring paragraphs. - reference/cli/marketplace.md synopsis lists both --path and --offline. - apm-usage commands.md: fold the two auto-merged "marketplace add" rows into one row carrying both the --path and the local apm.yml/--offline guidance. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…alogs Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…alogs Move the #3628 CHANGELOG bullet off the Added section edges so later landings that append to the section do not re-conflict. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
Merged current main into this branch (merge-of-main fallback; branch history already contains main merges): 021f236 -> 834157b (merge base a2c63ef). Conflicting paths resolved (faithful merge of both intents with #3367 live local apm.yml catalogs / --offline):
Also folded in the merge commit:
No regression-trap test changed in the merge, so the mutation-break gate was not re-run. Lint contract at 834157b: ruff check and ruff format --check silent; pylint R0801 10.00/10; lint-auth-signals.sh and lint-architecture-boundaries.sh exit 0; no src file over 2100 lines. Owner-touch gate re-detected at the new head (now also reports the live local authoring catalog owner via client.py); its suites and the original functional tests all pass. CI at 834157b: all required checks green. Post-push mergeability: Ready for maintainer review. This comment was generated by an AI agent (GitHub Copilot) on behalf of the maintainer. Please verify before acting on it. |
…-marketplaces Thread #3628's explicit catalog path through the canonical registration owner: probe_registration(..., explicit_path=) fetches only that file, and MarketplaceCatalogPathError carries the --path errors. marketplace add keeps --path admission and the replace warning; the source-admission owner row keeps both admit_marketplace_catalog_path and parse_registration_source. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Description
TL;DR
apm marketplace addgains--path, which registers a catalog stored anywhere inside a git-backed marketplace repository (for examplecatalogs/frontend/marketplace.json). The path is admitted once — contained, no traversal, must name a.jsonfile — saved in the registration, and reused bybrowse,search,updateandapm install. One repository can now serve one catalog per audience; registrations without--pathare unchanged.Note
Adjacent: open PR #3610 (#3006) moves this same probe block into a new
marketplace/registration.pyowner. This PR keeps its change to one small branch before auto-discovery so either merge order resolves mechanically; whichever lands second should threadexplicit_pathintoprobe_registration. The user-manifestmarketplaces:form from #3610 does not acceptpathyet — out of scope here.Problem (WHY)
apm.ymlholds onemarketplace:block, andmarketplace addonly probesmarketplace.json,.github/plugin/marketplace.json,.claude-plugin/marketplace.json. A catalog in a subfolder could not be registered, so per-audience catalogs needed one repository each ([FEATURE] : Support multiple marketplaces (catalogs) in one repository #3319).MarketplaceSource.pathalready existed and drove every fetch, but no CLI surface set it, and persisted values were never validated on reload.github/gitmarketplace sources takepath— "The marketplace file's path inside the repository. Defaults to.claude-plugin/marketplace.json". APM had no equivalent.Approach (WHAT)
--path PATHonmarketplace add: validated before any fetch, reads exactly that file (no auto-discovery), actionable error if escaping or missing, nothing registered on failure.marketplace-source-admissionowner (source_identity.py) instead of a new authority;MarketplaceSource.__post_init__routes persisted paths through it, so hand-edited../entries are skipped on load.admit_marketplace_catalog_path.Implementation (HOW)
src/apm_cli/marketplace/source_identity.py—admit_marketplace_catalog_path(): rejects empty, control chars, backslashes, absolute/drive paths, non-.json, and./../empty segments (viavalidate_path_segments, so percent-encoded%2e%2eis caught); drops one leading./.src/apm_cli/marketplace/models.py— non-emptypathis admitted in__post_init__; empty path (hosted URL / local file) unchanged.src/apm_cli/commands/marketplace/__init__.py—--pathoption, epilog example, docstring states discovery order. Rejected for hostedmarketplace.jsonURLs and direct local files (they already name the file). Local repository directories are accepted because they use the samepathfetch.scripts/architecture_linter/checks/marketplace_bundle_and_audit.py,.apm/architecture/owners/marketplace-plugins.json— guard literals and owner decision text extended.reference/cli/marketplace.md,consumer/installing-from-marketplaces.md,producer/publish-to-a-marketplace.md(new "One catalog per audience"),packages/apm-guide/.apm/skills/apm-usage/commands.md.Diagrams
Legend: how
marketplace addpicks the catalog file; the boxed branch is new, the others are unchanged.flowchart LR A["marketplace add SOURCE"] --> B{"--path given?"} B -->|no| C["probe marketplace.json, .github/plugin/, .claude-plugin/"] B -->|yes| D["admit_marketplace_catalog_path"] D -->|"invalid"| X["error, exit 1, nothing registered"] D -->|ok| E["_fetch_file at PATH only"] E -->|"missing"| X E -->|found| F["registry: path saved"] C --> F F --> G["browse / search / update / install read saved path"] subgraph NEW D E endTrade-offs
subdirentries, not local./sources. Verified withapm pack: a subfolderapm.ymlreads./entries relative to the subfolder at pack time, while consumers resolve relative sources from the repository root (Claude Code does the same for git sources). Changing install-time resolution was out of scope; the docs state the rule instead..jsonsuffix required. Catches the common mistake of passing a directory (catalogs/frontend) with a direct hint; Claude Code's field is also a file path._loadbehaviour for invalid URLs) rather than failing the whole registry.apm.ymlcovers it.Benefits
../, absolute, encoded) and missing paths fail before any registry write.--pathis byte-identical: same probe order, same error text, same stored shape.Issue and approved scope
Issue: Fixes #3319
Human scope-approval comment: #3319 (comment) (
apm-scope:v1, approved by Daniel Meppiel (@danielmeppiel); review contact Daniel Meppiel (@danielmeppiel)). Eligibility re-checked from a trustedorigin/maincopy:state: record-present,authorizes_implementation: false; fresh responsible-human confirmation relayed in the delivery session.Completes the issue: every Done-when item is covered — installed-CLI test registers two catalogs from one repository under different names and installs from each; path survives
marketplace update(all and named) and install; escaping/missing paths fail before registration; no---pathbehaviour unchanged; docs andapm-usage/commands.mddescribe option, recipe, discovery order, and access caveat. The issue's Q2 (both.github/plugin/and.claude-plugin/present) is answered in the docs: the first in probe order wins.Type of change
Testing
Local preflight skipped by maintainer instruction (2026-11-12); CI is the gate. Local runs were targeted only; the full unit suite was not run locally.
Scenario evidence
tests/integration/test_marketplace_catalog_path_lifecycle.py::test_two_catalogs_from_one_repository_register_install_and_refreshbackend-skill@acme-frontendexits 1);test_marketplace_catalog_path.py::TestMarketplaceAddPath::test_refresh_reads_the_recorded_path../, absolute, encoded, backslash, directory paths rejected before fetch or writeTestAdmitMarketplaceCatalogPath::test_rejects_escaping_or_malformed_paths,TestMarketplaceAddPath::test_invalid_path_fails_before_any_fetch_or_registrationTestPersistedRegistrationAdmission::test_registry_skips_hand_edited_escaping_entrytest_missing_path_fails_with_actionable_error+ lifecycle rejection sequence--path→ unchanged discovery and errortest_without_path_subfolder_catalog_is_not_discovered, existingtest_catalog_discovery_reuse.pytests/integration/test_architecture_marketplace_source_admission.py::test_marketplace_source_admission_guard_rejects_unrouted_catalog_pathValidation output
How to test
catalogs/a/marketplace.jsonandcatalogs/b/marketplace.json:apm marketplace add <repo> --path catalogs/a/marketplace.json --name a(repeat forb);apm marketplace listshows both paths.apm marketplace browse alists only catalog A's plugins;apm install <plugin>@aworks.apm marketplace add <repo> --path ../x.jsonand--path catalogs/missing/marketplace.jsonboth exit 1 with no registry change.apm marketplace add <repo>without--pathbehaves as before.Spec conformance (OpenAPM v0.1)
docs/src/content/docs/specs/openapm-v0.1.mdupdated(new/changed
<a id="req-XXX"></a>anchor + prose + Appendix Crow).
docs/src/content/docs/specs/manifests/openapm-v0.1.requirements.ymlupdated.
@pytest.mark.req("req-XXX")test undertests/spec_conformance/added or extended.CONFORMANCE.{md,json}regenerated viauv run --extra dev python -m tests.spec_conformance.gen_statementand committed.
src/apm_cli/marketplace/path is incritical_paths.txt.)Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com