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

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

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.

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