feat(pack): unify 'apm pack' to produce bundle and marketplace.json (closes #722)

[danielmeppiel]

feat(pack): unify apm pack to produce bundle and marketplace.json

TL;DR

Two build-shaped verbs (apm pack for bundles, apm marketplace build for marketplace.json) collapse into one: apm pack reads apm.yml and produces whichever artifacts the manifest declares — bundle when dependencies: is present, .claude-plugin/marketplace.json when marketplace: is present, both when both are. The marketplace_authoring experimental flag is removed (GA), and apm marketplace init now appends to apm.yml instead of scaffolding a standalone marketplace.yml. Closes #722.

Important

Breaking: apm marketplace build is deleted (no deprecation alias). Invoking it exits 2 with a one-line migration message. Update CI scripts to call apm pack.

Problem (WHY)

• Two verbs for one mental model. A user with dependencies: and marketplace: blocks in their apm.yml had to remember apm pack and apm marketplace build and run them in the right order. The user-reported framing: "now we have apm marketplace build and apm build / apm pack? this is bad ux." ([FEATURE] Add apm marketplace generate command to pack all plugins and produce a marketplace.json #722)
• Output path drift from Anthropic spec. The legacy command wrote marketplace.json to CWD, but Claude Code reads .claude-plugin/marketplace.json from the repo root per the official plugin marketplace spec. Publishers had to remember a manual copy step or risk pushing a stale file.
• Experimental gate hid GA functionality. marketplace_authoring had been stable for two minor releases; the apm experimental enable step was friction without a corresponding stability story.
• [!] Authoring entrypoint scaffolded the wrong file. apm marketplace init created a standalone marketplace.yml even after PR feat(marketplace): fold marketplace.yml into apm.yml's 'marketplace:' block (closes #722, implements #1036) #1038 made apm.yml the canonical home for the marketplace: block.

Why these matter: the user-facing surface had drifted from the PROSE principle: "Favor small, chainable primitives over monolithic frameworks." Two verbs that share a manifest, a lockfile, and an output directory are not chainable primitives — they are duplication. The Agent Skills guidance applies in mirror image: "Add what the agent lacks, omit what it knows" — the second verb added nothing the first could not infer from the manifest.

Approach (WHAT)

#	Change	Anchor
1	Single verb apm pack reads apm.yml, runs BundleProducer and/or MarketplaceProducer based on declared blocks.	Manifest is the control plane (npm/cargo precedent).
2	Delete apm marketplace build outright; install a custom error in the marketplace group that exits 2 with a migration hint.	Per maintainer directive: "do not deprecate things, just remove them."
3	Remove marketplace_authoring experimental flag and all its call sites + tests.	GA promotion.
4	Default marketplace output to .claude-plugin/marketplace.json (Anthropic-canonical). Override via --marketplace-output.	Claude Code marketplace spec.
5	apm marketplace init appends a marketplace: block to existing apm.yml (errors if missing or already present).	Authors a project; does not scaffold a parallel config file.
6	New flags scoped to marketplace producer: --offline, --include-prerelease, --marketplace-output.	Silent no-op when only bundle output is detected (matches npm pack flag-scope behavior).

Implementation (HOW)

• src/apm_cli/core/build_orchestrator.py (new, 274 lines) — Strategy pattern: BuildOrchestrator + ArtifactProducer Protocol + BundleProducer and MarketplaceProducer adapters. detect_outputs() does a raw YAML key check on apm.yml (plus a legacy marketplace.yml sibling check) to decide which producers to run. Producers are thin wrappers around the existing bundle.packer.pack_bundle and marketplace.builder.MarketplaceBuilder — no new build logic.
• src/apm_cli/commands/pack.py — Rewires the click command to build BuildOptions and call the orchestrator. Adds --offline, --include-prerelease, --marketplace-output. Help text rewritten to document the manifest-driven mental model with three example clusters (bundle-only, marketplace-only, both).
• src/apm_cli/commands/marketplace.py — Removes _authoring_visible() and _require_authoring_flag() and every call site. Adds MarketplaceGroup(click.Group) that catches the build subcommand name and raises UsageError with the migration message. apm marketplace init rewritten to operate on apm.yml via ruamel.yaml round-trip (preserves comments).
• src/apm_cli/core/experimental.py — marketplace_authoring entry deleted from the FLAGS dict.
• src/apm_cli/marketplace/init_template.py — Template now describes a marketplace: block to append, not a standalone file. All apm marketplace build references replaced with apm pack.
• Test churn — Deleted: tests/unit/commands/test_marketplace_{build,gating}.py. Added: tests/unit/core/test_build_orchestrator.py (14 tests), tests/integration/test_pack_unified.py (9 tests), tests/integration/test_azure_skills_marketplace.py (1 byte-identical-reproduction test). Net: -82 + 24 + 1 = -57 tests, all due to gate/build subcommand removal.
• Docs — docs/src/content/docs/guides/marketplace-authoring.md rewritten end-to-end. CLI reference, manifest schema, experimental.md, and the apm-usage skill all updated to match.

Diagrams

Legend: how apm pack routes a project's apm.yml to one or both producers; the dashed boxes mark the unified entrypoint and the new orchestrator that did not exist before this PR.

flowchart LR
    User([User runs<br/>apm pack]):::new
    Manifest[apm.yml]
    Detect{detect_outputs}:::new
    Orchestrator[BuildOrchestrator]:::new

    subgraph Producers
        Bundle[BundleProducer]
        Market[MarketplaceProducer]
    end

    Lockfile[(apm.lock.yaml)]
    BuildDir["./build/[name]/"]
    ClaudeDir[.claude-plugin/<br/>marketplace.json]

    User --> Orchestrator
    Orchestrator --> Detect
    Manifest --> Detect
    Detect -- "dependencies:" --> Bundle
    Detect -- "marketplace:" --> Market
    Detect -- "neither" --> Err[/exit 1:<br/>Nothing to pack/]:::new
    Bundle --> Lockfile
    Bundle --> BuildDir
    Market --> Manifest
    Market --> ClaudeDir

    classDef new stroke-dasharray: 5 5,stroke:#0969da,stroke-width:2px;

Loading

Legend: invocation flow when the project has both blocks — both producers run sequentially against the same manifest and lockfile, each writing to its canonical location.

sequenceDiagram
    participant U as User
    participant P as apm pack
    participant O as BuildOrchestrator
    participant B as BundleProducer
    participant M as MarketplaceProducer
    participant FS as Filesystem

    U->>P: apm pack
    P->>O: run(BuildOptions)
    O->>O: detect_outputs(apm.yml)
    Note over O: both blocks present<br/>routes to BUNDLE and MARKETPLACE
    O->>B: produce()
    B->>FS: write ./build/[name]/
    B-->>O: ProducerResult
    O->>M: produce()
    M->>FS: write .claude-plugin/marketplace.json
    M-->>O: ProducerResult
    O-->>P: BuildResult
    P-->>U: Packed 2 artifacts

Loading

Trade-offs

• Hard delete vs deprecation alias for apm marketplace build. Chose hard delete with a one-line migration error; rejected a transitional shim. Per repo policy: "we still favor shipping fast over lengthy deprecation cycles" (CLAUDE.md). The custom click error gives users a single clear migration step; a silent alias would let drift fester.
• No --marketplace-only / --bundle-only flags. Manifest is the control plane; users skip a producer by removing the corresponding block. Adding override flags would invite combinatorial nonsense (--bundle-only --marketplace-only = error? both?) and contradict the mental model.
• MVP keeps standalone marketplace.yml as a read-only legacy fallback. Already-deprecated; removal is queued for v0.13. Doing both (introduce orchestrator AND remove legacy reader) in one PR would balloon scope and break users mid-migration.
• Producers run sequentially, not in parallel. Both touch apm.yml/lockfile; parallelism risks contention for sub-second wall-clock gain. Revisit only if a third producer with isolated I/O appears.

Benefits

1. One verb to learn. New users discover apm pack from apm --help; the marketplace path no longer requires reading a separate doc page first.
2. Anthropic-spec output by default. Marketplace publishers can apm pack && git add .claude-plugin/marketplace.json && git commit — no manual copy step, no drift between the file Claude Code reads and the file apm writes.
3. Zero opt-in for marketplace authoring. apm experimental enable marketplace_authoring step removed from every quickstart.
4. Byte-identical reproduction of a real-world marketplace. tests/integration/test_azure_skills_marketplace.py clones (or replays a snapshot of) microsoft/azure-skills and asserts apm pack produces a marketplace.json with sha256 02f76bf...3b, matching the hand-authored file in that repo. This is regression coverage against future drift.
5. Single Strategy seam for future producers. Adding a third output (e.g., npm-registry push) is one new ArtifactProducer implementation, not a new top-level command.

Validation

uv run pytest tests/unit tests/test_console.py -x:

======================= 6706 passed in 88.34s (0:01:28) =======================

uv run pytest tests/integration/test_pack_unified.py tests/integration/test_azure_skills_marketplace.py -x:

======================== 10 passed in 4.21s ========================

uv run pytest tests/unit/core/test_build_orchestrator.py -x:

======================== 14 passed in 0.19s ========================

azure-skills reproduction (excerpt from test_azure_skills_marketplace.py::test_apm_pack_reproduces_azure_skills_marketplace_json_byte_for_byte):

expected sha256: 02f76bfc0e5bbf7fdf1de1dda1f84c4da6e986913b6647973c0ffe39c1d5003b
actual   sha256: 02f76bfc0e5bbf7fdf1de1dda1f84c4da6e986913b6647973c0ffe39c1d5003b
PASS

Files changed (40)

A  src/apm_cli/core/build_orchestrator.py        (+274)
M  src/apm_cli/commands/pack.py                  (~108 lines)
M  src/apm_cli/commands/marketplace.py           (gate removal + custom group)
M  src/apm_cli/commands/marketplace_plugin.py    (gate import removed)
M  src/apm_cli/commands/init.py                  (gate removed around --marketplace)
M  src/apm_cli/core/experimental.py              (FLAGS entry removed)
M  src/apm_cli/marketplace/init_template.py      (apm.yml block instead of standalone file)
M  src/apm_cli/marketplace/migration.py
M  src/apm_cli/marketplace/yml_editor.py
A  tests/integration/test_pack_unified.py        (9 tests)
A  tests/integration/test_azure_skills_marketplace.py (1 test)
A  tests/unit/core/test_build_orchestrator.py    (14 tests)
A  tests/fixtures/azure-skills/apm.yml
A  tests/fixtures/azure-skills/.claude-plugin/marketplace.json
M  tests/unit/marketplace/conftest.py            (fixture removed)
M  tests/unit/commands/conftest.py               (fixture removed)
D  tests/unit/commands/test_marketplace_build.py
D  tests/unit/commands/test_marketplace_gating.py
M  tests/unit/commands/test_marketplace_init.py
M  tests/unit/commands/test_marketplace_publish.py
A  tests/unit/marketplace/test_review_fixes.py
M  tests/unit/marketplace/test_apm_yml_marketplace_loader.py
M  tests/unit/marketplace/test_yml_schema.py
M  CHANGELOG.md
M  docs/src/content/docs/guides/marketplace-authoring.md
M  docs/src/content/docs/guides/marketplaces.md
M  docs/src/content/docs/reference/cli-commands.md
M  docs/src/content/docs/reference/experimental.md
M  docs/src/content/docs/reference/manifest-schema.md
M  packages/apm-guide/.apm/skills/apm-usage/commands.md
M  packages/apm-guide/.apm/skills/apm-usage/package-authoring.md
M  packages/apm-guide/.apm/skills/apm-usage/authentication.md
M  .github/aw/actions-lock.json
M  .github/workflows/agentics-maintenance.yml
M  .github/workflows/cli-consistency-checker.lock.yml
M  .github/workflows/daily-doc-updater.lock.yml
M  .github/workflows/daily-test-improver.lock.yml
M  .github/workflows/pr-review-panel.lock.yml
M  .github/workflows/triage-panel.lock.yml

Net: +2121 / -1579 across 40 files.

How to test

• git checkout fix/marketplace-fold-review-comments && uv sync --extra dev.
• In a project with only dependencies: in apm.yml, run apm pack → expect ./build/<name>/ only.
• In a project with only marketplace: in apm.yml, run apm pack → expect .claude-plugin/marketplace.json only.
• Run apm marketplace build → expect exit 2 with the one-line migration message pointing at apm pack.
• Clone https://github.com/microsoft/azure-skills, run apm pack in it, then sha256sum .claude-plugin/marketplace.json → expect 02f76bfc0e5bbf7fdf1de1dda1f84c4da6e986913b6647973c0ffe39c1d5003b.

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

[Copilot]

Pull request overview

Follow-up to the marketplace-authoring consolidation work (PR #1038), tightening edge-case handling around apm.yml parsing/migration/init flows and refreshing the public + embedded docs to reflect the single-apm.yml source-of-truth model.

Changes:

• Harden marketplace config detection/migration/init against malformed, empty, or non-mapping apm.yml inputs (with clearer typed errors).
• Add regression tests covering the reviewed edge cases.
• Refresh docs/guide content + command reference + schema docs + changelog entries to reflect the apm.yml marketplace: block authoring surface.

Show a summary per file

File	Description
tests/unit/marketplace/test_yml_schema.py	Renames a test to match updated local-path source behavior.
tests/unit/marketplace/test_review_fixes.py	Adds regression coverage for malformed/empty/non-mapping apm.yml scenarios and helper tightening.
tests/unit/marketplace/test_apm_yml_marketplace_loader.py	Corrects docstring to reflect unknown-key validation scope.
src/apm_cli/marketplace/yml_editor.py	Tightens _is_apm_yml_with_marketplace to require a mapping marketplace block.
src/apm_cli/marketplace/migration.py	Makes _has_marketplace_block surface read/parse errors; makes migration tolerate empty apm.yml and reject non-mappings.
src/apm_cli/marketplace/init_template.py	Updates module docstring to describe both template renderers.
src/apm_cli/commands/marketplace.py	Drops unused import; makes marketplace init handle empty/non-mapping apm.yml; updates .gitignore warning wording.
src/apm_cli/commands/init.py	Stops deriving marketplace owner from project name when --marketplace is used.
packages/apm-guide/.apm/skills/apm-usage/package-authoring.md	Updates embedded authoring docs to the apm.yml marketplace: model and adds migration guidance.
packages/apm-guide/.apm/skills/apm-usage/commands.md	Updates embedded command reference for marketplace authoring and apm init --marketplace.
docs/src/content/docs/reference/manifest-schema.md	Documents optional top-level marketplace: in apm.yml.
docs/src/content/docs/reference/cli-commands.md	Adds apm marketplace migrate reference; updates init/build/authoring docs for the apm.yml block model.
docs/src/content/docs/guides/marketplaces.md	Fixes legacy marketplace.yml reference to apm.yml.
docs/src/content/docs/guides/marketplace-authoring.md	Rewrites the guide around apm.yml marketplace: + .claude-plugin/marketplace.json output and migration/local-path packages.
CHANGELOG.md	Adds Unreleased entries describing the marketplace authoring consolidation/migration/init changes.

Copilot's findings

• Files reviewed: 15/15 changed files
• Comments generated: 4

[Copilot]

migrate_marketplace_yml() validates legacy marketplace.yml up front, but apm.yml is still parsed via ruamel without catching YAML parse errors. If apm.yml is malformed, this will raise a ruamel exception (and the CLI will surface a generic "Migration failed"), rather than a consistent MarketplaceYmlError like _has_marketplace_block(). Consider catching ruamel/yaml parse errors around rt.load(apm_text) and re-raising MarketplaceYmlError with an "Invalid YAML in apm.yml" message.

Suggested change

	apm_data = rt.load(apm_text)
	try:
	apm_data = rt.load(apm_text)
	except Exception as exc:
	from ruamel.yaml.error import YAMLError as RuamelYAMLError
	if isinstance(exc, RuamelYAMLError):
	raise MarketplaceYmlError("Invalid YAML in apm.yml.") from exc
	raise

[danielmeppiel]

Assessed the 4 copilot-pull-request-reviewer comments from 14:28 UTC; all addressed:

#	File	Status	Where
1	migration.py ruamel parse error	✅ wrapped in try/except yaml.YAMLError → MarketplaceYmlError	a322bfd (lines 82-87)
2	init.py --marketplace should require experimental flag	✅ superseded — marketplace_authoring flag deleted entirely (GA promotion)	dd5f558
3	CHANGELOG entries too long	✅ apm pack entry condensed from 418 → 165 chars	2b70e1e (this commit)
4	yml_editor.py missing type hint on data	✅ data: object annotation added	a322bfd

The reviewer's snapshot was taken before the GA-promotion + cleanup commits landed, so #2 reads as a regression but is actually obsolete — see the Removed section in CHANGELOG.