Marketplace output UX: filter-driven CLI + map-based manifest + JSON output

[danielmeppiel]

Marketplace output UX: filter-driven CLI + map-based manifest + JSON output

TL;DR

Refactor the apm pack marketplace surface so the manifest declares the universe and the CLI filters within it. Replace the asymmetric --marketplace-output (silently Claude-only) with format-symmetric flags that scale to the 3rd, 4th, Nth marketplace format with zero CLI churn.

Origin: follow-up to #1281 (review thread). Today's PR is sound and should ship; this issue tracks the surface that makes "write once, publish to every AI assistant" frictionless in CI/CD.

Problem

Today (post #1281):

marketplace.outputs: [claude, codex]      # list of names
marketplace.claude.output: PATH           # sibling block, per-format
marketplace.codex.output:  PATH           # sibling block, per-format
--marketplace-output PATH                  # CLI: silently claude-only

Three concrete UX bugs:

1. Asymmetric surface. apm pack --marketplace-output X reads as "set the marketplace path" but only touches Claude. CI scripts adopting outputs:[claude,codex] will silently drop the Codex artifact override, with no warning.
2. No CLI filter. No way to say "this CI matrix job builds claude only" without editing apm.yml. Matrix builds devolve into shell hacks or per-job manifest copies.
3. Magic-string registry. Adding cursor / windsurf / gemini later means another round of CLI-flag bikeshedding (--cursor-output? --marketplace-cursor? rename the existing flag again?).

flowchart LR
    subgraph today["TODAY (PR #1281)"]
        T1["apm.yml<br/>marketplace.outputs: [claude, codex]<br/>marketplace.claude.output: ...<br/>marketplace.codex.output: ..."]
        T2["apm pack<br/>--marketplace-output PATH<br/>(silently claude-only)"]
        T1 --> T2
    end

    subgraph target["PROPOSED"]
        P1["apm.yml<br/>marketplace.outputs:<br/>  claude: {}<br/>  codex: {path: ...}"]
        P2["apm pack<br/>--marketplace=claude,codex<br/>--output-path codex=PATH<br/>--json"]
        P1 --> P2
    end

    today -.->|"v0.14 migration"| target

Loading

Proposed UX

Principle: the manifest declares the universe. The CLI filters within it.

This is the convergent pattern across docker buildx --platform, goreleaser --id, webpack --config-name, cargo --target. APM's prior art (hugo outputs:) goes config-only; we go one better by exposing a clean CLI filter for CI matrices.

1. Manifest — outputs is a map

marketplace:
  outputs:                                 # MAP, not list
    claude: {}                             # path defaults to .claude-plugin/marketplace.json
    codex:
      path: .agents/plugins/marketplace.json
  packages:
    - name: foo
      source: ./plugins/foo
      category: Productivity               # required iff outputs.codex is configured

• One block per format. Per-format config (path, format-specific required fields) lives inside the entry. Eliminates the dual-source confusion (outputs: [claude, codex] selector + separate claude: + codex: sibling blocks).
• New formats add new keys; nothing else moves.
• Migration: outputs: [claude, codex] (list form) keeps parsing as shorthand for {claude: {}, codex: {}}; emits a one-cycle deprecation warning.
• apm marketplace init writes outputs: {claude: {}} explicitly so the next-step ("add codex") is discoverable in the file itself, not buried in docs.

2. CLI — filter, don't path-mutate

apm pack                                   # build every format in outputs:
apm pack --marketplace=claude              # filter to one
apm pack --marketplace=claude,codex        # comma list
apm pack --marketplace claude --marketplace codex   # repeatable (same as above)
apm pack --marketplace=all                 # explicit "every configured"
apm pack --marketplace=none                # skip marketplace entirely; bundle-only

Mental model: selection, never silent path mutation. Same idiom every developer who's used Docker, goreleaser, or cargo already knows.

3. Path overrides — namespaced, format-aware, CI-targeted

apm pack --output-path claude=./build/claude.json
apm pack --output-path claude=./build/claude.json --output-path codex=./dist/codex.json

Or via env (12-factor / secrets-friendly):

APM_MARKETPLACE_CLAUDE_PATH=./build/x.json apm pack

Format-named on both sides → impossible to silently narrow scope. Every future format gets path overrides for free with zero CLI churn.

4. Machine-readable output for CI

apm pack --marketplace=all --json

{
  "ok": true,
  "outputs": [
    {"format": "claude", "path": ".claude-plugin/marketplace.json", "packages": 12, "added": 1, "updated": 2, "unchanged": 9},
    {"format": "codex",  "path": ".agents/plugins/marketplace.json", "packages": 12, "added": 1, "updated": 2, "unchanged": 9}
  ],
  "warnings": []
}

This is the killer CI feature — jq -r '.outputs[].path' and pipe to actions/upload-artifact or gh release upload. Zero hardcoded paths in workflows.

5. Real deprecation for --marketplace-output

When the legacy flag is passed:

[!] --marketplace-output is deprecated; use --output-path claude=PATH or
    set marketplace.outputs.claude.path in apm.yml. Will be removed in v0.15.

Behavior auto-translates to --output-path claude=X for one minor cycle, then removed. Tracker: see linked removal issue.

6. Failure mode is the product

$ apm pack --marketplace=cursor
[x] Unknown marketplace format 'cursor'.
    Configured in apm.yml: claude, codex.
    Supported by APM:      claude, codex.

$ apm pack --marketplace=codex   # when yml has only {claude: {}}
[x] Marketplace format 'codex' is not configured in apm.yml.
    Add it under marketplace.outputs.codex, or run with --marketplace=claude.

Names what failed, why, one concrete next action. No tracebacks.

Behavior flow

flowchart TD
    A["apm.yml<br/>marketplace.outputs map"] --> B["MarketplaceConfig"]
    B --> C{"--marketplace filter?"}
    C -->|"unset / =all"| D["every configured format"]
    C -->|"=claude,codex"| E["filter to selected"]
    C -->|"=none"| F["skip marketplace<br/>(bundle only)"]
    D --> G["per-format build loop"]
    E --> G
    G --> H["MarketplaceOutputProfile<br/>registry lookup"]
    H --> I["Mapper.compose"]
    I --> J{"--output-path<br/>FORMAT=PATH?"}
    J -->|"yes"| K["use override"]
    J -->|"no"| L["use outputs.FORMAT.path<br/>or default"]
    K --> M["atomic write"]
    L --> M
    M --> N{"--json?"}
    N -->|"yes"| O["stdout JSON<br/>{outputs: [{format, path, ...}]}"]
    N -->|"no"| P["[claude] Built ...<br/>[codex]  Built ..."]

Loading

Adversarial review — build-tool peers

Reviewer	Verdict	Note
docker buildx --platform	✅ Direct match	Comma-separated multi-value filter on a single canonical flag is exactly the buildx idiom. Per-output progress prefix [claude] / [codex] already in #1281.
goreleaser --id	✅ Direct match	Filter-by-name within a config-defined registry. APM adds --json output, which goreleaser users routinely wish for.
webpack --config-name	✅ Match with one ask	Webpack supports --config-name='!claude' exclusion. Resolution: not v1; YAGNI. Comma list covers 95%; ship without exclusion until first user asks.
cargo --target	⚠️ Partial	Cargo's --target is single-value, repeated via shell loops. Resolution: APM accepts both comma-separated AND repeatable --marketplace foo --marketplace bar. Click multiple=True handles it.
rollup config-driven outputs	✅ Match	Rollup deprecated CLI --format in favor of config arrays — exactly the direction we're going.
hugo outputs:	✅ APM is better	Hugo never lets you filter at CLI — config only. Our --marketplace= is a strict superset for the CI matrix use case.
vite multi-config files	✅ APM is more disciplined	Vite encourages multiple config files; APM keeps one manifest. Cleaner mental model.
npm publish --tag	⚠️ Default-state caution	NPM was burned by changing default publish behavior. Resolution: bare apm pack builds whatever outputs: declares — never magical "all formats supported by APM." init writes the explicit {claude: {}} so the default is observable in the file.
terraform -target	✅ Lower-risk variant	Terraform's -target is dangerous (selective apply); ours is read-only-ish (selective build). Same UX, less footgun.

Convergent verdict: ship the filter-flag + namespaced-path-override + JSON-output trio. The two real concerns (default-state surprise, exclusion syntax) both resolve by not doing the speculative thing.

CI/CD beauty — the real test

Matrix publish (parallel jobs, one format each):

strategy:
  matrix:
    format: [claude, codex]
steps:
  - run: apm pack --marketplace=${{ matrix.format }} --json > pack.json
  - run: gh release upload "v${VERSION}" $(jq -r '.outputs[0].path' pack.json)

Single job, all formats, fan-out upload:

- run: apm pack --marketplace=all --json | tee pack.json
- run: |
    jq -r '.outputs[] | "\(.format) \(.path)"' pack.json | while read fmt path; do
      gh release upload "v${VERSION}" "$path" --label "marketplace-$fmt"
    done

Local dev (fast iteration on one format):

apm pack --marketplace=claude --dry-run    # preview claude
apm pack --marketplace=codex               # write only codex
apm pack --marketplace=none                # bundle only

Day-one when cursor ships — zero CLI changes:

marketplace:
  outputs:
    claude: {}
    codex: {}
    cursor:
      path: .cursor/marketplace.json

apm pack --marketplace=cursor --json       # works immediately

sequenceDiagram
    participant CI as GitHub Actions
    participant APM as apm pack
    participant FS as Workspace
    participant GH as gh release upload

    Note over CI: matrix.format = [claude, codex]
    CI->>APM: apm pack --marketplace=${matrix.format} --json
    APM->>FS: write per-format artifact
    APM-->>CI: stdout: {outputs:[{format, path, ...}]}
    CI->>CI: jq -r '.outputs[0].path' pack.json
    CI->>GH: upload $(path) labelled marketplace-${matrix.format}
    Note over GH: One release, one artifact per format,<br/>zero hardcoded paths in workflow

Loading

Why this matters strategically

This is the plugin point the OSS-growth-hacker persona called "untapped contributor funnel" in the #1281 review. Today, adding a marketplace format is a CLI-design discussion. Under this proposal, it's a one-file PR (output_profiles.py + a mapper). The CLI surface is invariant under format growth.

It also gives APM the strongest version of its "write once, publish to every AI assistant" positioning:

• The manifest is one block, observable in apm.yml review.
• The CLI is one flag, identical across formats.
• The CI artifact path is machine-readable; no shell hacks.
• The first new contributor adding cursor or windsurf ships their format end-to-end without touching any flag definitions.

Scope and milestones

v0.14 (this issue):

• Schema: outputs: accepts map form; list form continues to parse with deprecation warning
• apm marketplace init writes explicit outputs: {claude: {}} map
• apm pack --marketplace=<list> filter (comma + repeatable)
• apm pack --marketplace=all and =none sentinels
• apm pack --output-path <format>=<path> repeatable flag
• APM_MARKETPLACE_<FORMAT>_PATH env support
• apm pack --json machine-readable output
• --marketplace-output emits real logger.warning(...) (also tracked in linked removal issue) and auto-translates to --output-path claude=PATH
• Failure messages: unknown format, configured-but-missing format
• Docs: cli-commands.md, pack.md, publish-to-a-marketplace.md
• Test coverage: filter combinations, JSON shape stability, env-var precedence, deprecation warning

v0.15 (linked tracker issue):

• Remove --marketplace-output flag entirely

Out of scope

• Exclusion syntax (--marketplace='!claude') — defer until first user request
• Multiple apm.yml files / config inheritance — keep one manifest, one source of truth
• apm pack --format-help flag listing supported marketplace formats — nice-to-have, not a v0.14 blocker

References

• feat(marketplace): support multi-profile marketplace outputs #1281 — multi-profile marketplace outputs (the foundation this builds on)
• #1281 review thread on --marketplace-output
• Remove --marketplace-output flag in v0.15 #1318 — v0.15 tracker for removal of --marketplace-output

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/marketplace
area/cli
area/docs-site
type/feature
status/accepted
priority/high
dx

(Note: theme/portability, area/marketplace, area/cli, type/feature, and dx are already present as maintainer-applied labels and are correct. The panel adds area/docs-site, status/accepted, and priority/high.)

Milestone

0.14.0 (scoped in the issue body; maintainer should assign once the milestone is confirmed open)

Suggested next action

Open the schema migration PR first (outputs: map parsing + deprecation warning for list form + apm marketplace init update), then layer in --marketplace= filter and --output-path flags, then --json output, to keep review surface manageable.

Suggested issue comment

This is a strong proposal -- the "manifest declares the universe, CLI filters within it" principle resolves the three concrete UX bugs (asymmetric surface, no CLI filter, magic-string registry) cleanly, and the adversarial review table gives high confidence the design holds up against real build-tool peers.

The panel accepts this for v0.14. A few implementation notes:

- The schema migration (`outputs:` map-or-list) should land first, isolated in its own PR, so the parsing contract is stable before the CLI flags ride on top.
- `--output-path FORMAT=PATH` with `value.split('=', 1)` is straightforward Click parsing; the `APM_MARKETPLACE__PATH` env vars follow naturally from Click's `envvar=` parameter.
- The `--json` output shape (`{ok, outputs: [{format, path, packages, added, updated, unchanged}], warnings}`) should be treated as a public contract from day one -- add a schema stability test before release.
- Three doc pages are in scope (`cli-commands.md`, `pack.md`, `publish-to-a-marketplace.md`) plus `apm marketplace init` behavior; the implementing PR should include or explicitly track these.

The "write once, publish to every AI assistant" positioning this enables is the strongest version of APM's distribution story. Looking forward to the PRs.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

This proposal nails the developer tooling mental model. --marketplace=claude,codex directly mirrors docker buildx --platform linux/amd64,linux/arm64 -- an idiom that CI practitioners already have in muscle memory. --json output enabling jq -r '.outputs[].path' eliminates hardcoded artifact paths in CI workflows, which is the single biggest operational friction point today. The =all / =none sentinels are conventional and parseable. The failure mode error messages (unknown format; configured-but-missing format) each name what failed + why + one concrete next action -- the gold standard for actionable CLI errors. The adversarial review table is thorough: the two real concerns (default-state surprise; exclusion syntax) both resolve correctly by not doing the speculative thing.

Supply Chain Security Expert -- Risk-Surface Reviewer

apm pack produces marketplace artifacts (package manifests delivered to AI assistants), so this touches the distribution surface captured by theme/portability. The --output-path FORMAT=PATH flag and APM_MARKETPLACE__PATH env allow output path overrides -- the standard concern (path traversal/escape) applies equally to the existing marketplace.*.output field and should be validated at the same point in the existing code; no new surface. The deprecation of --marketplace-output is a breaking CLI change handled by a one-cycle migration policy -- proper governance. No theme/security or theme/governance override needed; theme/portability is the right primary theme. The --json output shape does not expose secrets (paths and counts only).

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author (danielmeppiel) is a COLLABORATOR with deep prior interaction; the proposal includes adversarial review tables, mermaid diagrams, and CI code examples. The suggested comment tone is peer-to-peer technical acknowledgement, not first-time-contributor onboarding.

Python Architect -- Architecture Reviewer

The outputs: map-or-list migration is clean: parse list form as {name: {} for name in list} with a deprecation warning -- backward compatible, no lockfile schema change. MarketplaceOutputProfile registry in output_profiles.py is the correct extensibility point: new format = new entry, zero CLI flag churn. Click multiple=True + comma-split for --marketplace is idiomatic. --output-path FORMAT=PATH parsing with value.split('=', 1) is non-standard but consistent with the goreleaser idiom cited and straightforward to implement. Cross-cutting scope (MarketplaceConfig parser, pack command, marketplace build loop, output writer, apm marketplace init) is well-bounded. The design is complete enough for implementation to start without a separate design document. Feasibility is high; recommend status/accepted.

Doc Writer -- Documentation Reviewer

Issue explicitly scopes three doc pages (cli-commands.md, pack.md, publish-to-a-marketplace.md) plus apm marketplace init behavior change. area/docs-site should be added as a secondary area label so the implementing PR is reminded. The issue body uses correct APM vocabulary throughout (apm pack, apm.yml, marketplace.outputs, apm marketplace init). The suggested comment wording echoes the "write once, publish to every AI assistant" framing from the README spine, which is the right anchor for this feature in the docs.

APM CEO -- Triage Arbiter

This is the cleanest kind of feature proposal: design-complete, adversarially reviewed, CI-use-case driven, and a direct extension of the v0.14 marketplace surface already in motion (#1281). The human-applied labels (theme/portability, area/marketplace, area/cli, type/feature, dx) are all correct and authoritative -- the panel adds area/docs-site (implied by explicit doc checklist), status/accepted (design is settled), and priority/high (v0.14-scoped, breaking CLI surface migration that increases ecosystem pain with delay). The "write once, publish to every AI assistant" positioning this enables is strategically significant: under this proposal, adding a new marketplace format is a one-file PR, making APM the low-friction hub for AI assistant distribution.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/marketplace", "area/cli", "area/docs-site"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": ["dx"],
  "milestone": "0.14.0",
  "next_action": "Open the schema migration PR first (outputs: map parsing + deprecation warning for list form + apm marketplace init update), then layer in --marketplace= filter and --output-path flags, then --json output.",
  "comment_markdown": "This is a strong proposal -- the manifest-declares-universe, CLI-filters-within principle resolves the three concrete UX bugs cleanly.\n\nThe panel accepts this for v0.14. Schema migration PR first, then CLI flags, then --json output. Three doc pages in scope. Looking forward to the PRs."
}

---

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.

Note

🔒 Integrity filter blocked 23 items

The following items were blocked because they don't meet the GitHub integrity level.

• #1120 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1122 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1130 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1138 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1156 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1157 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1209 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1210 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1220 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1222 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1225 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1231 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1260 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1266 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1273 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1279 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• ... and 7 more items

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Triage Panel · ● 1.1M · ◷