feat(marketplace): add package category option

[Ching Wei Kang (WilliamK112)]

Description

Add --category TEXT to apm marketplace package add and apm marketplace package set, following the existing --tags authoring path.

The category is persisted on the target marketplace.packages[] entry and remains independent of metadata in the source package manifest. Existing marketplace schema validation rejects blank values; the round-trip editor restores the original file when validation fails.

This also updates the CLI reference, bundled command guide, and marketplace authoring examples.

Fixes #2625

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Current-main reconciliation

• Merged current main at aa8a6820 in merge commit 309c3f82.
• Preserved the newer executable-trust details in the bundled apm doctor documentation while adding --category to the package add/set rows.
• Retained the parsed-YAML assertions and bundled command-guide update requested by Copilot.
• The PR remains limited to the same 8 implementation, test, and documentation files relative to current main.

Testing

• Tested locally
• All existing tests pass (full repository suite not run)
• Added tests for new functionality

Validation performed on the reconciled tree:

• Marketplace unit/integration tests plus CLI documentation contracts: 1,677 passed, 10 skipped
• Focused package command/editor tests: 71 passed
• Full ruff check src/ tests/: passed
• Full ruff format --check src/ tests/: 1,695 files already formatted
• Mypy passed for all changed source files
• Architecture boundary linter passed
• Docs build passed: 124 pages and 995 relative links checked
• Docs link test suite: 14 passed
• git diff --check origin/main: passed

Spec conformance (OpenAPM v0.1)

• N/A -- this PR does not change OpenAPM-observable behaviour.

[Copilot]

Pull request overview

Adds first-class --category TEXT support to marketplace package authoring commands so maintainers can set marketplace-owned package categories via CLI (parallel to the existing --tags workflow) and persist them onto marketplace.packages[].

Changes:

• Add --category option to apm marketplace package add and apm marketplace package set, persisting to marketplace.packages[].category via the round-trip YAML editor.
• Extend YAML editor support for writing/updating category on package entries (validated via existing schema revalidation + restore-on-failure behavior).
• Update CLI reference + producer authoring docs examples; add unit tests for persistence and blank-value rejection.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/unit/marketplace/test_yml_editor.py	Adds coverage that category is written on add/update paths.
tests/unit/commands/test_marketplace_plugin.py	Adds CLI tests ensuring --category is present and persisted; adds blank-category error/rollback checks.
src/apm_cli/marketplace/yml_editor.py	Adds category to add/update entry mutation logic.
src/apm_cli/commands/marketplace/plugin/set.py	Adds --category Click option and passes through to update logic.
src/apm_cli/commands/marketplace/plugin/add.py	Adds --category Click option and passes through to add logic.
docs/src/content/docs/reference/cli/marketplace.md	Documents the new --category flag in the CLI reference table.
docs/src/content/docs/producer/publish-to-a-marketplace.md	Updates authoring examples to show --category usage.

Suppressed comments (1)

tests/unit/commands/test_marketplace_plugin.py:244

• This assertion depends on the YAML text formatting (e.g., quoting). To test the behavior (category persisted on the target package entry), parse the YAML and assert on the loaded data structure instead of substring-matching the serialized file.

        )
        assert result.exit_code == 0, result.output
        assert "category: productivity" in yml.read_text(encoding="utf-8")

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Ching Wei Kang (WilliamK112)]

Resolved the current-main conflict in 309c3f82 by merging aa8a6820.

The only content conflict was in the bundled command guide. The resolution preserves the newer upstream apm doctor executable-trust text and keeps --category documented for both marketplace package add and set. The two earlier Copilot requests remain addressed.

Fresh validation on the merged tree:

• marketplace plus CLI docs-contract coverage: 1,677 passed, 10 skipped
• focused command/editor coverage: 71 passed
• full Ruff, Mypy, and architecture checks: passed
• docs build: 124 pages; 995 relative links; 14 link tests passed

GitHub now reports the PR as mergeable.