Blomios
5b55996558
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>
60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
# 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.
|
|
|
|
```sh
|
|
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.
|