# IdeA Plugin SDK

Public TypeScript SDK for IdeA plugins.

The SDK defines the stable manifest and runtime types used by plugins loaded by
IdeA. A plugin ships an `idea-plugin.json` manifest plus an ESM entrypoint that
exports `activate(ctx)`.

## Start Here

- [Manifest](docs/manifest.md): required fields, capabilities and contribution ids.
- [Activation And Context](docs/activation-context.md): `activate(ctx)`, lifecycle, logging, storage and subscriptions.
- [Menus](docs/menus.md): top-level menus, native menu insertion and command registration.
- [Commands And Feedback](docs/commands-and-feedback.md): command return values, skipped work and background tasks.
- [Layouts With React](docs/layouts-react.md): React/JSX/hooks layout authoring with host-provided React.
- [Windows](docs/windows.md): opening plugin layouts in detached OS windows.
- [Services](docs/services.md): workspace files and bounded `workspace.execTool`, tasks,
  tooling, events, config, terminal and windows facades.
- [Packaging And Distribution](docs/packaging-distribution.md): build output, archive layout, hot reload and dependency rules.
- [Codex Skills And IdeA Plugins](docs/codex-skills-and-idea-plugins.md): separate IdeA-native plugin skills from Codex plugin discovery.
- [Project Plugin Assignments](docs/project-plugin-assignments.md): enable plugins per project and assign skills and MCP tools to agents.

The installable example lives in [`examples/hello-plugin`](examples/hello-plugin).
It demonstrates a menu command, storage, background-task feedback, a React layout
component and `services.windows.open(...)`.

For short project-scoped external tools, use
`ctx.services.workspace.execTool()` with an explicit manifest
`permissions.workspaceExec` allow rule. See [Services](docs/services.md) and
[Manifest](docs/manifest.md). The primitive is generic and does not expose a
native Git/SCM API.

Menu commands that open or focus a plugin view return `status: "opened"`
(including `alreadyOpen: true`) and remain UI-silent on success. Keep diagnostic
views accessible when optional tools are missing, and use the structured
`skipped`/`failed` feedback contract for genuinely impossible actions; see
[Commands And Feedback](docs/commands-and-feedback.md) and [Menus](docs/menus.md).

## Install

```sh
npm install
```

## Build

```sh
npm run build
```

## Validate The Example

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

The example archive is written to:

```text
examples/hello-plugin/build/hello-plugin-0.1.0.zip
```