[FEATURE] apm.yml: support homepage, repository, keywords, and structured author fields

[sergio-sisternes-epam]

Problem

apm pack now generates plugin.json from apm.yml identity fields (#1597), but the generated manifests lack optional enrichment fields that hand-authored plugin.json files typically include:

• homepage -- project URL
• repository -- source code URL
• keywords -- discoverability tags
• author.url -- author website (currently author: is a plain string)

These fields are cosmetic (hosts do not require them), but their absence means projects migrating from hand-authored manifests lose metadata.

Evidence from microsoft/Build-CLI

The hand-authored files include fields that APM cannot currently express:

  # Fields present in hand-authored but missing from APM-generated
- "homepage": "https://github.com/microsoft/Build-CLI"
- "repository": "https://github.com/microsoft/Build-CLI"
- "keywords": ["microsoft", "build", "ignite", "events", "sessions", "learn"]
- "author": {"name": "Microsoft", "url": "https://www.microsoft.com"}
+ "author": {"name": "Microsoft"}  # url lost

Proposed solution

Extend the top-level apm.yml identity block to accept these optional fields:

name: microsoft-events
version: 1.0.5
description: Connect your project to Microsoft Build sessions.
author:
  name: Microsoft
  url: https://www.microsoft.com
license: Apache-2.0
homepage: https://github.com/microsoft/Build-CLI
repository: https://github.com/microsoft/Build-CLI
keywords: [microsoft, build, ignite, events, sessions, learn]

Backward compatibility

• author: Microsoft (string) continues to work, mapped to {"name": "Microsoft"}
• author: {name: Microsoft, url: ...} (object) adds the url field
• homepage, repository, keywords are optional -- omitting them changes nothing
• The marketplace schema already supports author as an object with {name, email, url} keys at the per-package level (_AUTHOR_OBJECT_KEYS in yml_schema.py)

Implementation scope

1. Update synthesize_plugin_json_from_apm_yml() in deps/plugin_parser.py to pass through homepage, repository, keywords, and structured author
2. Update build_plugin_manifest() in core/plugin_manifest.py to include these fields
3. Add tests for the new fields
4. Update docs: apm.yml reference, package-authoring guide

What this does NOT include

• Per-ecosystem overrides (e.g. different author.url for Claude vs Copilot) -- deferred
• Validation against URL schemas -- keep it permissive like the marketplace schema

Related

• [FEATURE] apm pack: generate plugin.json for Claude and Copilot ecosystems #1597 -- apm pack generates plugin.json (parent feature, merged)
• Add APM package manifest with marketplace support Build-CLI#39 -- the project that surfaced this gap

[github-actions]

Triage Panel Verdict

Issue: [FEATURE] apm.yml: support homepage, repository, keywords, and structured author fields
Decision: ACCEPT

---

Summary

This is a well-scoped, clearly motivated follow-on to #1597. The author provides concrete evidence from microsoft/Build-CLI#39 showing exactly which metadata fields are lost when migrating from hand-authored plugin.json to APM-generated manifests. The backward-compatibility story is sound (string author continues to work), and the implementation scope is tightly bounded.

Panel findings

Persona	Signal
DevX UX	Accept -- standard manifest fields expected by package authors from npm/pip/cargo ecosystems; their absence creates friction for migration
Supply Chain Security	No concerns -- cosmetic metadata fields, permissive validation is correct
Python Architect	Accept -- bounded 2-file change; _AUTHOR_OBJECT_KEYS precedent in yml_schema.py confirms object-form author is already partially modelled
APM CEO	Accept -- direct follow-on to merged #1597; real evidence from a microsoft project; no breaking changes; supports the "produce" promise for package authors

Decision

Type: Feature
Area: Package authoring
Theme: Portability (metadata fidelity from hand-authored to generated manifests)
Priority: Low (cosmetic but meaningful for authors migrating to APM-generated manifests)

Suggested implementation path

As proposed:

1. deps/plugin_parser.py -- extend synthesize_plugin_json_from_apm_yml() to pass through homepage, repository, keywords, and structured author
2. core/plugin_manifest.py -- extend build_plugin_manifest() to include these fields
3. Tests for all new fields (including string/object author dual-form)
4. Docs: apm.yml reference page + package-authoring guide

Per-ecosystem overrides and URL validation are correctly deferred.

Suggested milestone

v0.15 or next package-authoring milestone (maintainer to confirm based on roadmap).

---

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.

Generated by Triage Panel for issue #1621 · sonnet46 565.4K · ◷