[BUG] Plugin .lsp.json with lspServers wrapper key is silently skipped during install

[kkadete]

Describe the bug

When a marketplace plugin has a .lsp.json file using the standard { "lspServers": { ... } } format (as used by Claude Code and Copilot CLI), apm install silently skips all LSP servers from that plugin with a misleading error. The plugin's skill files install fine, but the LSP server never makes it into .github/lsp.json.

To Reproduce

1. Create a plugin with a .lsp.json in the standard format:

{
  "lspServers": {
    "my-lsp-server": {
      "command": "my-lsp",
      "args": ["--stdio"],
      "extensionToLanguage": {
        ".ext": "mylang"
      }
    }
  }
}

2. Add the plugin as a dependency in apm.yml
3. Run apm install

Expected behavior

my-lsp-server is registered and written to lsp.json.

Actual behavior

Skipping invalid LSP server 'lspServers' from plugin 'my-plugin': LSP dependency 'lspServers' requires 'command'

The LSP server is not written anywhere. No other error or indication that something went wrong.

Logs

[+] my-plugin (local)
[!] Skipping invalid LSP server 'lspServers' from plugin 'my-plugin': LSP dependency 'lspServers' requires 'command'
  |-- Skill integrated -> .agents/skills/
  |-- 1 skill(s) integrated -> .agents/skills/

Environment

OS: Windows
APM Version: 0.18.0
Python Version: 3.x

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/cli
type/bug
status/accepted
priority/high
good first issue

Milestone

null -- no open milestones found in the repository; assign to the next patch milestone when one is created.

Suggested next action

Fix the LSP parser to detect the { "lspServers": { ... } } wrapper key format and iterate its nested server entries instead of treating lspServers as a server name; add a regression test fixture with a wrapper-keyed .lsp.json.

Suggested issue comment

Thank you for filing this with a clear reproduction, @kkadete!

The bug is in the LSP config parser introduced in #1424. It iterates over the
top-level keys of `.lsp.json` and validates each as a server entry. When the file
uses the standard `{ "lspServers": { "my-lsp-server": { ... } } }` wrapper format,
the parser sees `lspServers` as a server name and reports that it lacks a `command`
key -- which is correct for flat-format validation but wrong for the wrapper format.

The fix is bounded: detect the `lspServers` wrapper key and iterate its nested
entries instead. The standard wrapper format is shipped by Claude Code and Copilot
CLI, so not handling it is a real interoperability gap for cross-ecosystem plugins.

If you would like to contribute the fix, the relevant code is in the LSP config
loading path that processes `.lsp.json` during `apm install`. A fixture with a
wrapper-keyed `.lsp.json` in the test suite would make sure this does not regress.
We would be happy to review a PR.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user task is: install a plugin and have its LSP server appear in .github/lsp.json.
The actual output is a misleading warning that names the wrapper key lspServers as an
invalid server entry, giving the user no actionable path forward. This violates the
"failure mode is the product" principle. The { "lspServers": { ... } } wrapper format
is the documented standard for Claude Code and Copilot CLI; supporting it is a
hard requirement for cross-ecosystem plugins to work. The fix is bounded to the LSP
parser; no UX redesign is required.

Supply Chain Security Expert -- Risk-Surface Reviewer

No P/G/S risk surface is implicated. The bug is confined to LSP config parsing during
install and does not affect lockfile integrity, signing, auth, or download paths. The
parser skips the wrapper-keyed entry rather than misinterpreting it in a
security-relevant way. No theme/security or theme/governance label required. Maps
to theme/portability (standard format interoperability) and area/cli (install
pipeline behavior).

OSS Growth Hacker -- Contributor-Tone Reviewer

Author kkadete has author_association=NONE, indicating a new or infrequent
contributor to this repository. The suggested comment is warm, validates the report
explicitly, explains the bug in plain language, and gives a concrete pointer to the
relevant code area. Tagging good first issue signals to the wider community that
the fix is approachable and well-scoped. The reply ends with a clear call to action
for a PR contribution.

Python Architect -- Architecture Reviewer

Not activated -- the bug is a targeted parser logic error in the LSP config loading
code and does not require a cross-cutting interface, schema, or module boundary change
to fix.

Doc Writer -- Documentation Reviewer

The implementing PR should verify whether LSP reference docs in docs/src/content/docs
document both the flat and the wrapper .lsp.json formats. If not, a short note
prevents future confusion from cross-ecosystem plugin authors. No separate area/docs-site
label is proposed as primary for this issue, but the PR description should include a
doc-check note. Suggested comment wording is grounded in APM install vocabulary.

APM CEO -- Triage Arbiter

Clear, bounded interoperability bug in the LSP integration pipeline introduced in
#1424. The { "lspServers": { ... } } wrapper format is standard for the two
dominant AI coding clients -- not handling it contradicts the "first-class LSP support"
positioning. This is a high-priority patch-level fix. No milestone is assigned because
no open milestones exist; a maintainer should slot it into the next patch milestone.
Marking good first issue is appropriate given the bounded scope and concrete
acceptance criteria. Decision ratified: accept, priority/high.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/cli"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": ["good first issue"],
  "milestone": null,
  "next_action": "Fix the LSP parser to detect the lspServers wrapper key and iterate its nested server entries; add a regression test fixture.",
  "comment_markdown": "Thank you for filing this with a clear reproduction, @kkadete! The bug is in the LSP config parser introduced in #1424. When the file uses the standard wrapper format, the parser sees lspServers as a server name and reports it lacks a command key. The fix is bounded: detect the lspServers wrapper key and iterate its nested entries."
}

---

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 · sonnet46 4.1M · ◷