IdeaSDK/docs/menus.md

Menus

Menus are declared in the manifest and implemented by registering command handlers during activation.

{
  "contributes": {
    "menus": [
      {
        "id": "hello-plugin.menu",
        "label": "Hello Plugin",
        "topLevel": true,
        "order": 100
      }
    ],
    "menuItems": [
      {
        "id": "hello-plugin.open.item",
        "targetMenuId": "hello-plugin.menu",
        "label": "Open Dashboard",
        "command": "hello-plugin.open",
        "order": 10,
        "when": "projectOpen"
      }
    ]
  }
}

Then register the command id:

export function activate(ctx: ActivateContext): void {
  const disposable = ctx.commands?.registerCommand("hello-plugin.open", async () => {
    const win = await ctx.services?.windows.open({ layoutType: "hello-plugin.dashboard" });
    return win
      ? { status: "opened", alreadyOpen: win.alreadyOpen }
      : { status: "skipped", reason: "ui-service-unavailable", message: "UI service unavailable." };
  });
  if (disposable) ctx.subscriptions.push(disposable);
}

Rules

• There is no separate contributes.commands collection. A command can only be registered if at least one manifest menuItems[].command or slashCommands[].command entry declares that exact id.
• A missing command handler is surfaced by the host as a retryable reload error; menu clicks must never fail silently.
• A registered handler's rejected promise is not swallowed: the host logs the plugin id, command id, status, reason and message, then presents a generic retryable error without raw payloads. In particular, return/await services.windows.open(...) so native-window failures follow this path.
• An open/focus handler returns status: "opened" whether alreadyOpen is false (new window) or true (existing window focused). Neither success produces an alert.
• Keep diagnostic views reachable when optional executables such as Git, ADB or Gradle are missing. Let the view explain that degraded state instead of skipping the menu action before opening it.
• A handler owns precondition checks and feedback. See Commands And Feedback.
• Menu item when expressions are evaluated by the host; unsupported or false conditions hide/disable the item according to host policy.

Targets

targetMenuId can refer to a plugin top-level menu id or a host menu id exposed by IdeA. Prefer a plugin top-level menu for plugin-specific workflows and host menus only when the action naturally belongs beside native actions.