# IdeA Plugin SDK

Minimal public TypeScript SDK for IdeA plugins.

This first version intentionally stays small:

- public manifest types for `idea-plugin.json`;
- public runtime types for plugin modules exposing `activate(ctx)`;
- a lightweight manifest validator;
- a minimal `examples/hello-plugin` plugin.

## Install

```sh
npm install
```

## Build

```sh
npm run build
```

## Typecheck the example

```sh
npm run typecheck:examples
```

## Build the installable hello plugin archive

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

The archive is written to:

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

Its ZIP root contains `idea-plugin.json` directly, with no wrapping parent directory. The
compiled ESM entrypoint is emitted at `dist/index.js`, matching the manifest `main` field.

## Plugin shape

An IdeA plugin ships an `idea-plugin.json` manifest and a JavaScript entrypoint built from
TypeScript.

```json
{
  "ideaPluginManifestVersion": 1,
  "id": "com.example.hello",
  "displayName": "Hello Plugin",
  "version": "0.1.0",
  "main": "dist/index.js",
  "trustLevel": "full",
  "contributes": {}
}
```

The entrypoint exports an `activate(ctx)` function:

```ts
import type { ActivateContext } from "@idea/plugin-sdk";

export function activate(ctx: ActivateContext): void {
  ctx.logger.info("hello from plugin");
}
```

## Manifest Validation

```ts
import { validatePluginManifest } from "@idea/plugin-sdk";

const result = validatePluginManifest(manifestJson);
if (!result.success) {
  console.error(result.errors);
}
```

This validator is deliberately strict for core fields and permissive about future unknown fields.
It is not a security boundary.