[FEATURE] Add `apm marketplace generate` command to pack all plugins and produce a `marketplace.json`

[Antonin-Rouxel-LaPoste-BGPN]

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

The apm pack --format plugin command can produce a self-contained plugin bundle from a single apm.yml project. However, there is no way to do this for an entire collection of plugins at once, nor to generate the resulting marketplace.json that aggregates them for discovery and governance.

The apm marketplace command group exists but only covers consuming marketplaces (add, browse, list, remove, update). There is no way to produce a marketplace index from a set of local plugin projects without writing custom scripts.

This forces teams to maintain their own generation scripts (e.g. a Node.js script that walks a plugins/ directory, calls apm pack --format plugin on each, and assembles marketplace.json by hand), which is error-prone and not portable.

Describe the solution you'd like

Introduce a dedicated marketplace.yml definition file at the root of the repository that declares which plugin projects to include in the marketplace. apm marketplace generate would read this file to know what to compile, then pack each plugin and assemble the resulting marketplace.json.

Example marketplace.yml:

name: my-org-marketplace
version: 1.0.0
description: Internal plugin marketplace for my organization

plugins:
  - path: plugins/halo-angular/
  - path: plugins/other-plugin/

Add a new apm marketplace generate subcommand that:

1. Reads marketplace.yml (or a path passed via --config) to determine which plugin projects to include.
2. Runs apm pack --format plugin on each declared plugin path, which produces each plugin's plugin.json and associated build artifacts.
3. Reads each generated plugin.json to collect resolved metadata.
4. Produces the marketplace.json file defined in the output field, aggregating all plugins — meaning a single command indirectly generates all plugin.json files and the final marketplace.json.

Proposed usage:

# Generate marketplace.json using marketplace.yml at current directory
apm marketplace generate

# Or with an explicit config path
apm marketplace generate --config ./marketplace.yml

This single command would replace the following manual sequence:

cd plugins/halo-angular && apm pack --format plugin
cd plugins/other-plugin  && apm pack --format plugin
# ... then manually assemble marketplace.json

Expected output (marketplace.json):

{
  "name": "my-org-marketplace",
  "metadata": {
    "description": "Internal plugin marketplace for my organization",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "owner": {
    "name": "My org",
    "email": "my-org@example.fr"
  },
  "plugins": [
    {
      "name": "halo-angular",
      "version": "1.0.0",
      "description": "APM project for halo-angular",
      "source": { "source": "github", "repo": "org/repo" }
    }
  ]
}

Describe alternatives you've considered

• Custom scripts: Writing a Node.js/Python script per repository to walk plugin directories, invoke apm pack, and assemble marketplace.json. This works but is not portable and must be duplicated across every team using APM.
• Manual editing: Maintaining marketplace.json by hand. This is error-prone and breaks as soon as plugin versions are bumped.
• apm marketplace add + apm marketplace update: These commands manage the local marketplace registry for consuming plugins, not for publishing/generating a marketplace index file.

[danielmeppiel]

Coming back to this with the broader vision after working through the marketplace cluster (#676 reframe, #677 scope reduction). Want to record where we're heading so the design conversation can continue with shared context.

@Antonin-Rouxel-LaPoste-BGPN — the marketplace.yml design you proposed is the right foundation. What follows is the 10x version that composes with the rest of the roadmap. Command names below are tentative — UX needs design (hence needs-design).

Maintainer journey (the dream)

# 1. Initialize the marketplace once
apm marketplace init                     # creates marketplace.yml + .claude-plugin/

# 2. Develop your packages normally in packages/*/
#    Each has its own apm.yml with version: field

# 3. When ready to release, generate the catalog
apm marketplace generate
#    -> runs apm pack --format plugin per package (reusing existing primitive)
#    -> resolves each package's latest matching prefixed tag (+ SHA)
#    -> composes marketplace.json with git-subdir sources
#    -> validates output against Anthropic's schema (uses #757)
#    -> writes marketplace.json + per-package plugin.json files
#    -> prints a summary diff vs. previous version

# 4. Lint (CI-friendly)
apm marketplace generate --check         # exits non-zero if marketplace.json is stale
apm marketplace lint                     # validates marketplace.json against schema

# 5. Atomic release flow (companion)
apm marketplace publish code-reviewer@1.3.0
#    -> tags code-reviewer-v1.3.0
#    -> bumps ref + sha in marketplace.json
#    -> opens PR (or commits directly with --no-pr)
#    -> optionally cuts a GitHub Release for transport optimization

Capabilities that make it 10x

Capability	Why it matters
marketplace.yml config (per the design above)	Declarative source of truth; explicit list of which packages are published
Auto-detect mode (marketplace.yml optional)	Walk packages/*/apm.yml by glob — zero-config for simple layouts
Per-entry prefixed-tag resolution	Reads each package's apm.yml version: field, looks up <name>-v<version> git tag and SHA — no hand-pinning
Diff + dry-run	--dry-run shows the planned marketplace.json delta before writing
Schema validation against Anthropic spec	Wires in #757; fail loudly if output drifts from the published schema
Multi-target output	Generate marketplace.json plus variant files if Copilot CLI's schema differs (parallels APM's multi-target install philosophy via #529)
Per-entry content_hash	SHA-256 per package stored in entry — feeds the per-file content-hash roadmap item, gives consumers tamper detection
--check mode for CI	Drop into a GitHub Action: PR fails if marketplace.json is stale w.r.t. packages — same UX as cargo fmt --check / prettier --check
Companion publish	Atomic per-package release: tag -> bump -> PR. Inherits SHA pinning automatically. Replaces the publish piece of #677 without spec extension.
Companion lint	Standalone validator (consumers can lint third-party marketplace.json files too — supports trust workflows)
pluginRoot smart-default	Reads metadata.pluginRoot from marketplace.yml so entries can use bare names

Composition with the rest of the roadmap

• [FEATURE] Allow multiple targets in apm.yml #529 multi-target — generate respects targets: per package; marketplace.json entries reflect what each package supports.
• Per-file content-hash (Next on roadmap) — entries carry hashes; apm install verifies before deploying.
• Audit & Policy v2 (Next on roadmap) — apm audit validates that installed package hashes match the marketplace.json they came from (drift detection across the supply chain).
• Marketplace add source parity with the Anthropic spec #676 consumer-side parity — generate could optionally produce a remote-hostable marketplace.json ready for the new apm marketplace add <URL> source shape.
• [Feature] Document marketplace.json schema  #757 schema docs — lint and generate --check read directly from these docs as their contract.

Sergio's #677 work feeds in here

MarketplaceValidator and the apm marketplace publish skeleton from #677 are directly reusable — they just need to operate on standard marketplace.json (one ref per entry, prefixed tags) instead of the invented versions[] array. That's exactly the scope reduction request in #677. Once landed in slim form, the publish piece migrates here as the atomic-release companion.

Open design questions

1. Command surface naming. generate / publish / lint / init mirror common toolchain verbs (cargo, npm) — but is generate the right verb for "compose the catalog from N packages"? build? assemble? compose? Worth a short design pass before implementation lands.
2. marketplace.yml vs. a section in root apm.yml. Standalone file is clearer separation; nested keeps it discoverable. Default leaning: standalone, optional auto-detect mode covers the simple case.
3. publish PR-vs-direct policy. Default: open PR. --no-pr flag for direct commit on solo maintainer setups. Worth checking against Antonin's actual workflow.
4. Companion file generation. The Cloudflare RFC is on hold (see Marketplace add source parity with the Anthropic spec #676), but if generate could also produce a .well-known/agent-skills/index.json later, design the output paths now to leave room for it.

What this unlocks

This is the kind of feature that turns marketplace maintainers into APM evangelists. Single command from a monorepo of N packages -> fully-pinned, validated, optionally signed marketplace.json published as an atomic release. No tool in this space ships the full loop today.

Marking needs-design. Happy to converge on the verbs and the marketplace.yml schema shape in a follow-up before implementation. Anyone wanting to take a swing at the design doc — speak up here and let's coordinate.

[sergio-sisternes-epam]

Continuing the design pass

Picking this up — I've been iterating on a concrete design for the maintainer surface that builds on #677 and answers the open questions above. Sharing here for feedback before anything lands.

TL;DR: your vision holds. A full command-flow simulation surfaced ~45 UX risks that drove a few departures from the original sketch, and one hard rule that drives everything else.

Hard rule: marketplace.json is Anthropic's standard, unaltered

This is the anchor of the whole design:

• Zero schema deviation. The marketplace.json APM emits conforms byte-for-byte to Anthropic's schema. No APM-specific keys, no extensions, no renamed fields.
• Interchangeable artifact. A marketplace.json produced by APM must be indistinguishable from one produced by Claude Code's native tooling. Third-party Anthropic schema validators must pass cleanly.
• Anthropic key names preserved verbatim. plugins, metadata.pluginRoot, and every other field Anthropic defines are emitted exactly as Anthropic defines them — regardless of APM's internal terminology.
• APM build inputs live only in marketplace.yml and are stripped at compile time. Specifically: build: (top-level), and per-entry version: (range), ref:, subdir:, tag_pattern:, include_prerelease:. These never appear in the json.
• Schema extension requires Anthropic action, not APM. If APM needs a new field in the json, we advocate for it upstream or keep it yml-only. We never silently extend the standard.

Enforced by a golden-file test: compiled output must validate against Anthropic's schema and round-trip through Claude Code without changes.

Answers to the four open questions

1. Command verb — build, not generate. Shorter, matches the "compose a catalogue from many parts" model, consistent with other APM verbs (apm pack, apm install).

2. marketplace.yml — standalone only for now. Nested-in-apm.yml deferred; clearer separation for maintainers.

3. publish default — open PR, full atomic. --no-pr as the escape hatch. Transactional: update yml -> validate tag -> rebuild json -> commit -> push -> gh pr create, recorded in .apm/publish-state.json so we can --resume/--abort mid-sequence.

4. Companion files -> schema room reserved. Output path is pluggable (output: + pass-through metadata:), so later additions never break the schema.

Departures from the original sketch

• Terminology. marketplace.yml uses packages: (APM's term). On compile, APM translates packages: -> plugins: so the json matches Anthropic verbatim. All user-facing text (CLI, help, docs) says "package"; the translation is invisible to maintainers and absent from the artifact-schema contract.
• Entry model. Git-only. Every packages[] entry references an external git repo by source: owner/repo (+ optional subdir:); no local paths, no direct relation to apm pack --format plugin. Monorepos work via subdir: + per-entry tag_pattern:.
• marketplace.json committed alongside the yml. It's the artifact consumers fetch, so init does not gitignore it. First phase mitigates merge-conflict risk via branch protection + Phase 2 post-merge CI rebuild hook.
• versions[] array dropped. Per feat: marketplace UX, security hardening, and lockfile provenance (#514) #677's scope reduction. Version pinning lives in the prefixed git tag <name>-v<version> on the package's source repo. publish validates that tag exists; it does not create it.
• Three new commands in addition to your set:
  • apm marketplace outdated — maintainer-side discovery (otherwise there's no way to tell when upstream tags have moved).
  • apm marketplace doctor — preflight probe for git / gh / tokens / ls-remote; collapses a long auth-debug loop into one command.
  • check subsumes freshness, so CI has one command.

Schema (first version)

name: my-org-marketplace
description: Internal package marketplace
version: 1.0.0
owner: { name: Acme Corp, email: platform@acme.example }
output: marketplace.json

# Anthropic schema pass-through (emitted verbatim into marketplace.json)
metadata:
  pluginRoot: ./plugins

# APM-only build config (stripped on compile; never appears in marketplace.json)
build:
  tagPattern: "v{version}"         # default; overridable per entry

packages:
  - name: code-reviewer
    source: acme/code-reviewer
    version: ^1.0.0                # APM-only (range -> resolved ref + sha)
    description: AI-powered PR review
    tags: [ci, code-review]
  - name: ci-investigator
    source: acme/ci-investigator
    ref: v2.1.0                    # explicit pin
  - name: doc-writer
    source: acme/tools-monorepo
    subdir: packages/doc-writer
    version: ^0.3.0
    tag_pattern: "{name}-v{version}"
    include_prerelease: true

UX preview (abridged)

All output uses APM's ASCII STATUS_SYMBOLS convention.

$ apm marketplace build
[>] Resolving 3 packages (8 workers, 10s timeout)...
[+] code-reviewer      ^1.0.0            v1.1.0   a1b2c3d
[+] ci-investigator    v2.1.0 (pinned)            b2c3d4e
[+] doc-writer         ^0.3.0            v0.3.2   c3d4e5f
=== Diff vs previous marketplace.json ===
  code-reviewer     v1.0.5 -> v1.1.0   (was 4d5e6f7, now a1b2c3d)
  doc-writer        (new)              v0.3.2   c3d4e5f
=== End diff ===
[+] Wrote marketplace.json (3 packages, 1 new, 1 updated)

$ apm marketplace outdated
PACKAGE           CURRENT   LATEST    RANGE     COMMAND
code-reviewer     v1.1.0    v1.2.0    ^1.0.0    apm marketplace publish code-reviewer@1.2.0
ci-investigator   v2.0.0    v2.1.0    ^2.0.0    apm marketplace publish ci-investigator@2.1.0
doc-writer        v0.3.2    v0.3.2    ^0.3.0    (up to date)

$ apm marketplace check --strict
[>] refs           [!] ADVISORY: code-reviewer v1.2.0 SHA changed
                         previously: e4f5g6h  (.apm/version_pins.json)
                         currently:  9z8y7x6
                         Likely ref-swap or upstream retag.
                         To accept: apm marketplace publish code-reviewer@1.2.0 --accept-ref-change
[x] --strict: 1 advisory treated as error. Exit 2.

$ apm marketplace publish code-reviewer@1.2.0 --dry-run
[>] Preflight
    base branch        main
    working tree       clean
    target branch      marketplace/publish-code-reviewer-1.2.0 (available)
    gh scopes          repo, workflow  [+]
[>] Validate tag       acme/code-reviewer@v1.2.0 -> e4f5g6h  [+]
[>] Planned yml change packages[code-reviewer].ref: (none) -> v1.2.0
[>] Planned json diff  code-reviewer  v1.1.0 -> v1.2.0   (a1b2c3d -> e4f5g6h)
[>] Planned git        stage + commit + push + gh pr create
[i] --dry-run: no files written.

$ apm marketplace doctor
[>] git                           [+] 2.42.0
[>] gh                            [+] 2.40.0 (scopes: repo, workflow)
[>] Token discovery               [+] GITHUB_TOKEN (env)
[>] Sample ls-remote (private)    [+] OK (340 ms)
[+] All checks passed. Rate limit: 5000 req/h.

Hardening surfaced by simulation

• Tag pattern diversity. Configurable tag_pattern: (v{version}, {version}, {name}-v{version}, release-{version}); auto-probe if unset.
• Authentication & rate limits. Token discovery (GITHUB_TOKEN -> GH_TOKEN -> gh auth token -> credential helper); shared ref cache (TTL 5 min); wrapped git stderr with actionable hints.
• Non-TTY contract. Central _maybe_prompt() helper; destructive actions need explicit flags in CI (--yes, --accept-ref-change + --i-know-what-im-doing, --allow-downgrade).
• Publish rollback. Transactional state file; --resume/--abort; safe force-push restricted to branches whose HEAD commit carries our own Co-authored-by trailer.
• Prerelease handling. Strict semver by default; opt-in via include_prerelease: or --include-prerelease.

Out of scope (Phase 2+)

Consumer-side UX (inspect/diff/trust), remote marketplace.json URLs in check, batch publish (publish --all), unpublish, cross-repo push-to-publish automation, marketplace author <verb> subgroup.

---

Happy to iterate. If the direction feels right, I can lift the full plan (UX-risk register, absorption map, todo breakdown) into a design doc — comment here or a separate issue, whichever you prefer.