blomios/IdeaSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
15f930dd3bb036709c40418e0426fdb4adf6ce42
IdeaSDK/examples/hello-plugin/README.md
Blomios 5b55996558 docs(sdk): fige le contrat command-and-feedback et aligne l'exemple hello-plugin 
Documente la règle publique menu -> command handler -> tâche de fond optionnelle
-> feedback (docs/commands-and-feedback.md + README), clarifie via JSDoc les
invariants de runCommand/recordOnly/ownerAgentId dans runtime.ts, et met à jour
l'exemple hello-plugin (feedback structuré launched/skipped, watch non-fatal)
pour qu'il illustre fidèlement le contrat documenté. Publie docs/ dans le
package npm.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-03 15:51:30 +02:00

2.8 KiB
Raw Blame History

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 as hello-world.
  • plugin-owned storage: activation count, command run count and initialization flag;
  • tooling capability: logs the focused workspace project when ctx.services is available.

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.ts and src/core/workspace.ts hold feature logic.
  • src/core/storage.ts keeps plugin-owned counters and flags in ctx.storage.

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://. 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 and the compiled multi-file ESM output under dist/, including dist/index.js, matching the manifest main field.

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.

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.