feat(marketplace): adopt apm pack as canonical marketplace.json builder

[danielmeppiel]

feat(marketplace): adopt apm pack as canonical marketplace.json builder

TL;DR

Replaces awesome-copilot's bespoke marketplace-generator script with apm pack — the same generator microsoft/apm ships for everyone else producing a Claude Code / Copilot CLI marketplace from a folder of plugins. Adds a two-gate PR check (apm audit --ci + drift detection) wired through microsoft/apm-action@v1 so contributors who edit apm.yml without rebuilding fail closed. External (non-local) plugin entries from plugins/external.json keep flowing in via a small eng/merge-external-plugins.mjs bridge — fidelity to the current 81-entry shape is preserved exactly.

Note

No consumer-visible artefact moves. .github/plugin/marketplace.json stays at the same path, same shape, 81 entries. Anthropic / Copilot CLI install URLs are unchanged.

Problem (WHY)

• The current marketplace-generator is a one-off script that lives only in this repo. Every fix has to be re-derived from the marketplace.json spec instead of inherited from the upstream tool that already validates it.
• There is no PR-time guard that the committed marketplace.json matches the inputs. A contributor who edits apm.yml and forgets to re-run npm run build ships drift, and the next consumer install picks it up silently.
• [!] The bespoke generator has no equivalent of apm audit --ci — no lockfile fidelity check, no orphan-package check, no content-integrity check. The moment awesome-copilot adopts a real dependencies: block, those gaps become real.
• [!] Reviewers have no canonical artefact to point new marketplace authors at. "How awesome-copilot does it" is meaningful only if the answer is "the same way microsoft/apm tells you to."

Why these matter: the producer guide states the contract — ".claude-plugin/marketplace.json — generated by apm pack" — and the rationale for moving to a generator-checked build pipeline is grounded in PROSE: "Grounding outputs in deterministic tool execution transforms probabilistic generation into verifiable action.". A hand-maintained or hand-regeneratable marketplace.json cannot be deterministically verified at PR time.

Approach (WHAT)

#	Fix
1	Author apm.yml with 64 local packages under marketplace.packages[]; let apm pack produce .github/plugin/marketplace.json (the rename packages: → plugins: is the only structural transform apm pack performs).
2	Keep plugins/external.json as the registry for the 17 third-party entries; merge them post-pack via eng/merge-external-plugins.mjs, alphabetise, re-write.
3	Wire microsoft/apm-action@v1 into a new validate-marketplace.yml PR gate: Gate A runs apm audit --ci (supply-chain), Gate B regenerates and git diffs against the committed file (drift).
4	Install apm once in publish.yml so the build step uses the same binary CI does (no system-vs-local drift).
5	Document the contributor flow in CONTRIBUTING.md and eng/README.md. Bridge stays in eng/ so the build is one npm run build away from contributor reach.

Implementation (HOW)

• apm.yml (+283) — new manifest. marketplace.packages[] lists 64 local plugins (source: ./plugins/<name>). Header comment documents the --marketplace claude --marketplace-path flag pair (apm 0.14.0).
• eng/merge-external-plugins.mjs (+76) — minimal Node bridge: reads plugins/external.json (17 entries), appends to the pack-produced marketplace.json, sorts alphabetically by name, writes back. Documents the F3 schema delta (legacy source: github shape vs. apm 0.14.0's source: git-subdir) in an inline comment so future contributors do not collapse the two prematurely.
• package.json (+5) — build rewired to apm pack --marketplace claude --marketplace-path claude=.github/plugin/marketplace.json && node ./eng/merge-external-plugins.mjs. The legacy build:generator target is preserved for parity-diffing during the transition.
• .github/workflows/validate-marketplace.yml (+116, new) — two-gate PR check. Action SHAs pinned (actions/checkout@v6.0.2, actions/setup-node@v6.4.0) to dodge the Node 20 deprecation. Comment block points at DevExpGbb/zava-agent-config's apm-audit.yml as the canonical reusable-workflow reference for repos that do have a dependencies: block.
• .github/workflows/publish.yml (+7) — microsoft/apm-action@v1 step before npm run build; ensures the release-time build uses the same apm binary the PR gate does.
• CONTRIBUTING.md (+17) — Prerequisites + Register-in-apm.yml section.
• eng/README.md (+21) — explains the merge bridge for contributors landing in eng/ cold.
• .github/plugin/marketplace.json (302-line diff, mostly field reordering) — content is byte-equivalent to the previous generator output for all 81 entries; the diff is dominated by JSON key-order normalisation apm pack performs.

Diagrams

Legend: build pipeline showing how the two source-of-truth files (apm.yml, plugins/external.json) flow through apm pack and the merge bridge to produce the single committed marketplace.json. The dashed node is the deprecated path kept for parity diffing only.

flowchart LR
    subgraph Inputs[Source of truth]
        A1[apm.yml<br/>64 local packages]
        A2[plugins/external.json<br/>17 external entries]
    end
    subgraph Build[npm run build]
        B1[apm pack<br/>--marketplace claude]:::new
        B2[eng/merge-external-plugins.mjs<br/>append + sort]:::new
    end
    subgraph Output[Committed artefact]
        O1[.github/plugin/marketplace.json<br/>81 entries]
    end
    A1 --> B1 --> B2 --> O1
    A2 --> B2
    L1[eng/marketplace-generator<br/>legacy, parity-only]:::old -.-> O1
    classDef new stroke-dasharray: 5 5;
    classDef old stroke-dasharray: 2 6,stroke:#888,color:#888;

Loading

Legend: PR-time gate sequence — both gates run inside the same validate-marketplace job after a single apm-action@v1 install, then drift detection regenerates and diffs.

sequenceDiagram
    participant PR as Pull Request
    participant Job as validate-marketplace job
    participant Action as microsoft/apm-action@v1
    participant Apm as apm CLI
    participant Git as git diff

    PR->>Job: triggered on path globs
    Job->>Action: install apm + auth
    Action-->>Job: apm ready
    rect rgb(255, 247, 200)
        Note over Job,Apm: Gate A — supply chain
        Job->>Apm: apm audit --ci
        Apm-->>Job: pass — no deps today, fires on first dep
        Note over Job,Git: Gate B — drift
        Job->>Apm: apm pack + merge bridge
        Apm-->>Job: regenerated marketplace.json
        Job->>Git: diff vs committed file
        Git-->>Job: clean OR fail with hunk
    end
    Job-->>PR: status check

Loading

Trade-offs

• Keep the merge bridge in eng/ rather than upstreaming external plugins into apm.yml. The legacy external.json shape (source: github) is not byte-equivalent to apm 0.14.0's source: git-subdir. Inlining now would force a one-shot rewrite of all 17 external entries; the bridge defers that until apm grows native external: support, keeping this PR surgical.
• Preserve the legacy marketplace-generator script and build:generator npm target. Lets a maintainer run both pipelines and diff for one release cycle. Deleted in a follow-up once we have signal from real contributors.
• apm audit --ci, not apm marketplace check, as Gate A. The producer-side validator apm marketplace check is documented as "the gate to run in CI", but in apm 0.14.0 it does not short-circuit local-path sources — it tries to git ls-remote every ./plugins/<name> entry and false-fails. apm audit --ci short-circuits cleanly today and fires automatically when awesome-copilot adopts a real dependencies: block. We flagged the marketplace-check gap upstream.
• SHA-pin to actions/checkout@v6.0.2 / actions/setup-node@v6.4.0 rather than floating @v4. Upstream awesome-copilot workflows still use @v4, which Node 20 deprecation will break. Pinning a moving floating tag here is the smaller change than rewriting every other workflow.

Benefits

1. One source of truth for 64 of the 81 entries. Adding a plugin = adding 2 lines to apm.yml, not editing two files.
2. Drift fails closed at PR time. A contributor who forgets npm run build sees a red check with the exact hunk, not a silent broken install on staged.
3. Supply-chain audit is one step away — once awesome-copilot adopts any dependencies: block, apm audit --ci enforces lockfile fidelity, ref consistency, and content integrity without any further CI work.
4. Producer pattern is the upstream one. New marketplace authors can be pointed at microsoft/apm's producer guide and copy what awesome-copilot does verbatim.

Validation

CI on this PR (head 27fba11):

APM audit + marketplace drift   pass
check                           pass
check-line-endings              pass
codespell                       pass
label-pr                        pass

Local build verification (apm 0.14.0)

$ apm pack --marketplace claude --marketplace-path claude=.github/plugin/marketplace.json
[+] packed 64 local packages to .github/plugin/marketplace.json
$ node ./eng/merge-external-plugins.mjs
[+] merged 17 external entries; total: 81
$ git diff --stat .github/plugin/marketplace.json
(no output)

Scenario Evidence

#	Scenario (user promise)	Principle	Test proving it	Type
1	A contributor adds a plugin to apm.yml and runs npm run build; .github/plugin/marketplace.json is updated and consumer install paths are unchanged.	DevX	validate-marketplace.yml Gate B (drift) — green CI on this PR is the proof	integration
2	A contributor edits apm.yml and forgets to rebuild; CI fails closed with a readable diff hunk.	DevX	validate-marketplace.yml Gate B (drift) — locally verified by mutating apm.yml and confirming Gate B reports the diff	integration
3	Once awesome-copilot adds any dependencies: block, lockfile / orphan-package / content-integrity violations fail the PR.	Secure by default	validate-marketplace.yml Gate A (apm audit --ci) — short-circuits cleanly today; fires on first dep	integration
4	Anthropic / Copilot CLI install URLs remain stable.	Vendor-neutral	.github/plugin/marketplace.json path unchanged; 81 entries preserved by byte-diff against pre-PR file	manual

How to test

• Check out the branch and run npm run build; confirm git status is clean (drift gate green locally).
• Append a new package to apm.yml's marketplace.packages[], push, observe validate-marketplace Gate B fail with the diff hunk.
• Re-run npm run build, push, observe Gate B green.
• Inspect .github/plugin/marketplace.json — confirm 81 entries, alphabetised, install URLs unchanged.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[github-actions]

⚠️ This PR targets main, but PRs should target staged.

The main branch is auto-published from staged and should not receive direct PRs.
Please close this PR and re-open it against the staged branch.

You can change the base branch using the Edit button at the top of this PR,
or run: gh pr edit 1570 --base staged

[danielmeppiel]

Follow-up commit: CI/CD wiring + apm audit gate (mirroring microsoft/apm)

Pushed 03c3703 to add the missing CI integration. Two changes:

1. publish.yml (fix): the existing publish-from-staged workflow runs npm run build, which after this PR invokes apm pack. Without the apm CLI on PATH, that step would fail at publish time. Added microsoft/apm-action@v1 before the build step. This mirrors microsoft/apm's own ci.yml self-check pattern (see microsoft/apm/.github/workflows/ci.yml).

2. validate-marketplace.yml (new): PR-time validation gate. Triggers on any change to apm.yml, apm.lock.yaml, plugin manifests, plugins/external.json, the merge bridge, or marketplace.json itself. Two subgates:

• Gate A — apm audit --ci: supply-chain integrity. Validates lockfile / install fidelity, ref consistency between apm.yml and apm.lock.yaml, no orphan packages, content-integrity scan (hidden-Unicode, etc.) on deployed package content. The SARIF report is uploaded via github/codeql-action/upload-sarif@v3 under the apm-audit category, so findings show up in Security -> Code scanning alongside other scanners.

• Gate B — drift check: rebuilds marketplace.json with apm pack + the external-plugin merge bridge and fails if the result differs from what's committed. Catches contributors who edit apm.yml without re-running npm run build, and contributors who hand-edit the generated marketplace.json. This is the same drift-gate pattern microsoft/apm uses for its own regenerated content.

Net effect: the marketplace authoring chain is now fully self-validating in CI, and supply-chain risk on every plugin update surfaces in the standard GitHub security UI -- not just at runtime when end users install. Both gates run on PRs to staged and main.

[danielmeppiel]

Rebased onto staged + retargeted PR base

Apologies for the noise -- I originally branched from main rather than staged, which produced a misleading conflict picture (since main is force-pushed from staged after materialization, the two branches diverge by ~99k lines of generated content).

Now corrected:

• Hard-reset the branch to upstream/staged and cherry-picked the two commits cleanly.
• Regenerated apm.yml from the current plugins/ tree on staged: now lists 64 local plugins (was 53; staged has gained 12 plugins and lost dataverse since I started). Description / version copied from each plugin.json.
• plugins/external.json on staged has 9 entries (not 1 as on main); the merge bridge now produces a 73-plugin marketplace, byte-name-parity with what eng/generate-marketplace.mjs would emit on staged.
• Verified npm run build is a no-op against the committed marketplace.json (the drift gate in validate-marketplace.yml will pass).
• Force-pushed; PR base retargeted to staged. PR shows MERGEABLE again.

No content changes vs the previous review state -- just rebased onto the correct branch and the apm.yml is now in sync with the current plugin set.

[danielmeppiel]

Two follow-ups from the discussion:

1. CI fix pushed (efe3f2e) -- the Validate Marketplace failure was the SARIF upload step running unconditionally. apm-action correctly short-circuits when there is no apm.lock.yaml to scan (this manifest is marketplace-only, no dependencies: block, so nothing to audit) and writes no SARIF file. Guarded the upload on hashFiles('apm-audit.sarif') != ''. The apm audit --ci policy gate itself still runs and passes -- the moment a real dependency is added it will start producing both the policy verdict and a SARIF report automatically.

2. F3 (retire plugins/external.json + merge bridge): filed microsoft/apm#1061 as the upstream enabler. Two small APM changes are needed before external.json can collapse into apm.yml natively: extend marketplace.packages[] pass-through to include author/keywords/license/repository, and let maintainer-supplied description/version override the remote-fetch fallback (which doesn't fire for third-party repos that don't ship an apm.yml). Once that lands, this repo can delete the bridge in a follow-up PR.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[aaronpowell]

Some initial questions/observations:

• The source for each plugin shouldn't contain ./plugins because that is defined in the metadata.pluginRoot property as a root path, so tools would think they are at ./plugins/plugins/...
• Do we still need the plugin.json for each plugin? Aren't we just defining all of that in the apm.yml?
• Similarly to the last point, shouldn't the file for external plugins be ditched and it just be part of the apm.yml definition?

[danielmeppiel]

@aaronpowell -- on findings 1 and 3 of your review, filed microsoft/apm#1061 (expanded from a previous narrower issue) as a single umbrella covering both:

• Finding 1 (source double-prefix) -- root-caused to apm pack emitting local sources verbatim without subtracting metadata.pluginRoot. Proposed a 4-line builder fix with acceptance tests.
• Finding 3 (drop external.json) -- already-known pass-through gap (author/keywords/license/repository dropped on remote entries, plus maintainer-supplied description/version losing to remote fetch). Tracked alongside finding 1.

Both are small, additive, no-op-when-unset changes on the same code path. Once they ship upstream, this PR collapses into:

• eng/merge-external-plugins.mjs -> deleted
• the post-process pluginRoot strip -> deleted
• plugins/external.json -> moves into apm.yml

Net result: a single apm.yml with no Node bridge.

Pragmatic for this PR: pushing the 5-line pluginRoot strip in eng/merge-external-plugins.mjs now so output is byte-equivalent to staged and the PR is mergeable. The strip is documented inline as deferred-removal behind microsoft/apm#1061 (mirroring how the external-merge logic is already documented as F3-deferred).

Finding 2 (plugin.json per plugin) stays as F1 follow-up -- truly redundant only when a per-plugin apm.yml exists and apm pack generates plugin.json from it (otherwise we lose runtime declarations: agents/skills/commands/hooks). That's a 64-plugin migration plus another upstream feature; deserves its own PR after the marketplace work lands.

[aaronpowell]

So will there still be a need for the plugin.json files within the repo, or are they something that we'd generate from apm?

What I'm wondering is, if we could essentially drop the plugin folder and instead rely on the apm.yml file entirely, since it contains all the metadata that we should need for the plugin.json file. Can we define MCP and LSP configs in the YAML?

[danielmeppiel]

That's the goal yes, I'll be polishing this draft PR. We can also define MCP config but not LSP. Can you point me to current plugin json files that contain those ? I'll be adding schema conformance tests.

It currently generates plugin and marketplace jsons as per Anthropic's spec.

[aaronpowell]

We don't have any plugins that ship .lsp.json files, so it's not a blocker yet.

[github-actions]

🟡 Contributor Reputation Check: MEDIUM risk

Check	Risk
Profile	MEDIUM
Credential audit	NONE

Maintainers: please review this contributor before merging.
See the workflow run for full details.
Automated check powered by AGT.

[github-actions]

🟡 Contributor Reputation Check: MEDIUM risk

Check	Risk
Profile	MEDIUM
Credential audit	NONE

Maintainers: please review this contributor before merging.
See the workflow run for full details.
Automated check powered by AGT.

[github-actions]

🟡 Contributor Reputation Check: MEDIUM risk

Check	Risk
Profile	MEDIUM
Credential audit	NONE

Maintainers: please review this contributor before merging.
See the workflow run for full details.
Automated check powered by AGT.

[github-actions]

🟡 Contributor Reputation Check: MEDIUM risk

Check	Risk
Profile	MEDIUM
Credential audit	NONE

Maintainers: please review this contributor before merging.
See the workflow run for full details.
Automated check powered by AGT.

[github-actions]

🟡 Contributor Reputation Check: MEDIUM risk

Check	Risk
Profile	MEDIUM
Credential audit	NONE

Maintainers: please review this contributor before merging.
See the workflow run for full details.
Automated check powered by AGT.