IdeaSDK/examples/hello-plugin/README.md

Hello Plugin

Installable IdeA plugin example rebuilt from the public SDK types.

It exercises the current plugin primitives end to end:

• top-level menu: Hello Plugin;
• menu entry: hello-plugin;
• command: hello-plugin, returning readable feedback: { status: "launched", taskId, state, message } when it starts a background task, or { status: "skipped", reason, message } when a precondition is not met;
• layout contribution: hello-plugin.hello-world, rendered by a React/JSX component with hooks.
• plugin window: the menu command opens the layout through ctx.services.windows.open(...) when services are available.
• plugin-owned storage: activation count, command run count and initialization flag;
• tooling capability: logs the focused workspace project when ctx.services is available.
• packaged command script: resolves scripts/hello-task.mjs from the official ctx.pluginRoot and launches it with the project kept as the task working directory.

The source is intentionally split across multiple TypeScript modules:

• src/index.ts is the manifest entrypoint and imports relative ESM modules;
• src/constants.ts owns shared command/layout identifiers;
• src/core/layout.tsx and src/core/workspace.ts hold feature logic.
• src/core/storage.ts keeps plugin-owned counters and flags in ctx.storage.
• scripts/hello-task.mjs is a read-only runtime resource included in the archive.

The build uses plain tsc; it does not bundle the plugin into one file. The archive includes all compiled dist/**/*.js files so IdeA can load dist/index.js and serve its package-relative imports through idea-plugin://. React and ReactDOM are peer dependencies resolved to the host instance at runtime. Other runtime imports from node_modules are outside this contract: vendor them as relative files or bundle them into the plugin output before packaging.

npm run typecheck:examples
npm run package:hello-plugin

The installable archive is emitted at examples/hello-plugin/build/hello-plugin-0.1.0.zip. It contains idea-plugin.json at the ZIP root, the compiled multi-file ESM output under dist/, including dist/index.js, and the packaged handler under scripts/hello-task.mjs.

Diagnostics

During activation the plugin logs:

• whether the command and layout runtime registries are available;
• whether plugin-owned storage is available;
• activation count and initialization state stored through ctx.storage;
• successful registration of the hello-plugin command;
• successful registration of the hello-plugin.hello-world layout;
• availability of the workspace service from the tooling runtime capability;
• best-effort workspace watch setup, including a non-fatal log when unavailable;
• the first layout render, including project/node identifiers;
• plugin window open/focus results from ctx.services.windows.open(...).

During command invocation the plugin logs and returns structured feedback for programmatic callers. The current human menu-click UI does not guarantee display of that return value.

• skipped command feedback when no project or no helloPlugin.ownerAgentId is available;
• launched background command feedback when helloPlugin.ownerAgentId is configured;

These messages are intentionally small and stable so installation, bundle import, activation and layout rendering failures can be separated quickly in IdeA logs/devtools.