# 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 stable `ctx.services` facade for workspace, background task and terminal operations;
- 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");
}
```

## Runtime Services

Plugins declaring the `tooling` capability receive `ctx.services`. Plugins
without that capability do not receive this facade. Prefer `ctx.services` over
IdeA's internal runtime objects when it is available:

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

export async function activate(ctx: ActivateContext): Promise<void> {
  const project = await ctx.services?.workspace.getCurrentProject();
  ctx.logger.info("current project", project);

  const task = await ctx.services?.tasks.getStatus("task-id");
  ctx.logger.info("task status", task?.status);

  const terminal = await ctx.services?.terminal.open({ rows: 24, cols: 80 });
  await terminal?.write(new TextEncoder().encode("echo hello\\r"));
}
```

Current terminal scope is intentionally minimal: it opens or reattaches a shell
PTY, writes bytes, resizes, detaches and closes. The background task service is
observation/control only in this SDK version: `list`, `getStatus`, `attachOutput`,
`cancel` and `retry` operate on existing tasks visible through IdeA's Work read
model. Starting new background tasks is not part of the public plugin API in this
lot.

Declare the additive `tooling` capability to receive `ctx.services` at runtime:

```json
{
  "capabilities": ["ui", "tooling"]
}
```

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