Files

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

src

docs(sdk): fige le contrat command-and-feedback et aligne l'exemple hello-plugin

2026-08-03 15:51:30 +02:00

idea-plugin.json

Initial commit: IdeaSDK TypeScript plugin SDK

2026-08-02 16:24:59 +02:00

package-lock.json

Initial commit: IdeaSDK TypeScript plugin SDK

2026-08-02 16:24:59 +02:00

package.json

Initial commit: IdeaSDK TypeScript plugin SDK

2026-08-02 16:24:59 +02:00

README.md

docs(sdk): fige le contrat command-and-feedback et aligne l'exemple hello-plugin

2026-08-03 15:51:30 +02:00

tsconfig.build.json

Initial commit: IdeaSDK TypeScript plugin SDK

2026-08-02 16:24:59 +02:00

tsconfig.json

Initial commit: IdeaSDK TypeScript plugin SDK

2026-08-02 16:24:59 +02:00

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 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.