IdeA/sdk/IdeaSDK

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

npm install

Build

npm run build

Typecheck the example

npm run typecheck:examples

Build the installable hello plugin archive

npm run package:hello-plugin

The archive is written to:

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.

{
  "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:

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:

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:

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

Manifest Validation

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.