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);
• plugin-owned persistent storage through ctx.storage;
• a stable ctx.services facade for workspace, background task and terminal operations;
• public workspace file APIs for reading, writing, listing, stat and path resolution;
• a bounded generic project-structure query API;
• public command-task APIs for launching and tracking generic tools;
• public external-toolchain diagnostics for executables, env vars and files;
• public best-effort event subscriptions and workspace watch;
• public structured config-document helpers for JSON documents;
• a lightweight manifest validator;
• a minimal examples/hello-plugin plugin.

Command And Feedback Contract

Plugin menu actions follow one public contract:

menu click -> registered command handler -> optional background task -> feedback surfaces

A menu item only names a command. The registered command handler owns all precondition checks, task launch decisions and feedback. If a command cannot or should not start work, return a small structured result such as { status: "skipped", reason, message } and log the same reason. That return value is useful for programmatic callers, agents and future host surfaces; the current human menu-click UI does not guarantee that handler return values are shown to the user. Do not create a background task just to represent a skipped command.

Use ctx.services.tasks.runCommand() only after required preconditions are true: a focused project exists, the plugin has the tooling capability, required executables/files/env are present, and a real ownerAgentId is available when the result belongs to an agent workflow. ownerAgentId controls Work ownership, cancellation and completion delivery; it must not be a placeholder in production plugin code.

recordOnly: true records completion without waking the owner agent. It is not a silent mode and it does not hide the task from surfaces that show Work state or background-task events. If no task is launched, the baseline feedback surfaces are the command result for programmatic callers and plugin logs; human-visible UI feedback requires a host-supported surface, a real background task, or a plugin-owned UI/file surface.

Canonical rules and examples live in docs/commands-and-feedback.md.

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, alongside the other compiled files imported by that entrypoint.

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",
  "activationScope": "app",
  "contributes": {}
}

activationScope is optional and defaults to "app", which activates the plugin at app bootstrap without requiring a focused project. Use "activationScope": "project" only when activate(ctx) needs project-scoped services immediately; IdeA will keep that plugin pending until a project is focused, then activate it once for the app session.

The main field is the ESM entrypoint loaded by IdeA. It may import other JavaScript files from the same plugin package with relative specifiers:

import { COMMAND_ID } from "./constants.js";
import { useWorkspaceSdk } from "./core/workspace.js";

Those relative imports are served by IdeA through the idea-plugin:// protocol, so plugins do not need to be bundled into a single JavaScript file. A plain tsc build that emits multiple ESM files under dist/ is supported, as shown by examples/hello-plugin.

Only package-relative imports are resolved this way. Bare specifiers such as react, lodash or any dependency expected from node_modules are not resolved by the host at runtime. Third-party dependencies must be bundled into the plugin output or vendored as relative files shipped inside the plugin package.

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");
}

Layout Runtime

Plugins can contribute custom layout panels by declaring contributes.layouts in idea-plugin.json and registering the matching layout type during activate(ctx).

{
  "contributes": {
    "layouts": [
      {
        "type": "com.example.status",
        "label": "Status",
        "component": "StatusPanel"
      }
    ]
  }
}

import type { ActivateContext, PluginLayoutProps } from "@idea/plugin-sdk";

function StatusPanel(props: PluginLayoutProps): string {
  return `status for ${props.projectId}`;
}

export function activate(ctx: ActivateContext): void {
  const disposable = ctx.layouts?.register({
    type: "com.example.status",
    component: StatusPanel
  });
  if (disposable) ctx.subscriptions.push(disposable);
}

Public layout props are:

• projectId: project hosting the layout cell;
• nodeId: stable layout node id for that cell instance;
• layoutType: contributed layout type from the manifest;
• state: opaque JSON-serializable state persisted by the host;
• setState(next): replaces that state;
• availability: currently "available" when the component is mounted.

Lifecycle: register layouts during activate(ctx), keep the returned disposable in ctx.subscriptions, and let the host dispose it on plugin unload. Layout components may be mounted, unmounted and remounted by the host; keep durable UI state in state via setState, not in module globals. Call setState from user actions, effects or asynchronous callbacks, not unconditionally while rendering. Services are available from ctx.services to plugins declaring the tooling capability; layout props do not expose private runtime gateways.

Plugin-Owned Storage

Use ctx.storage for state owned by the plugin itself: internal counters, flags, preferences, small caches and host-facing settings. This is the canonical place for plugin-owned state because the host can scope and persist it outside the user's project files.

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

const ACTIVATION_COUNT_KEY = "helloPlugin.activationCount";

export async function activate(ctx: ActivateContext): Promise<void> {
  const current = await ctx.storage?.get<number>(ACTIVATION_COUNT_KEY);
  const next = typeof current === "number" ? current + 1 : 1;
  await ctx.storage?.set(ACTIVATION_COUNT_KEY, next);

  ctx.logger.info("activation count", { next });
}

Do not write plugin-internal state into .ideai/* or other project files by default. Use workspace files and config-document helpers only when the file is project-owned content or project-owned configuration that the user expects to see, review and version with the project.

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"));
}

Workspace Files

Workspace paths are always relative to the project root. Hosts reject absolute paths, .., empty path segments and paths outside the sandbox. Text APIs use UTF-8; binary APIs use Uint8Array. Missing files reject on reads and resolve to { exists: false } from stat. These APIs are for project-owned files: source files, generated reports or user-visible artifacts. Use ctx.storage instead for plugin-owned counters, flags, preferences and caches.

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

export async function activate(ctx: ActivateContext): Promise<void> {
  const workspace = ctx.services?.workspace;
  const project = await workspace?.getCurrentProject();
  if (!workspace || !project) return;

  await workspace.writeTextFile("hello-plugin-report.txt", "hello\n", project.id);

  const file = await workspace.readTextFile("hello-plugin-report.txt", project.id);
  const listing = await workspace.listDirectory(".", project.id);
  const stat = await workspace.stat(file.path, project.id);

  ctx.logger.info("workspace file", {
    path: file.path,
    bytes: stat.len,
    entries: listing.entries.length
  });
}

watch(path, handler, projectId?) subscribes to public workspace file-change events for the given relative path. It is best-effort and bounded: hosts may reject it until workspace watching is implemented, and plugins must treat setup failure as non-fatal. Plugins should also handle missed events by refreshing their own derived state when needed.

Project Structure

queryStructure() returns a bounded, generic read model so plugins do not each need to rescan the whole workspace for common markers:

const structure = await ctx.services?.workspace.queryStructure({
  maxDepth: 3,
  maxEntries: 500
});

for (const convention of structure?.conventions ?? []) {
  console.log(convention.id, convention.markerPath);
}

The MVP detects generic marker-file conventions such as package.json, Cargo.toml, pyproject.toml, go.mod, Makefile and .git. It deliberately does not expose language-specific ASTs or Android-specific concepts.

Current terminal scope is intentionally minimal: it opens or reattaches a shell PTY, writes bytes, resizes, detaches and closes.

Command Tasks

Use ctx.services.tasks.runCommand() for non-interactive tools that should be tracked as IdeA background tasks instead of opening a raw PTY. command and args are passed separately, cwd is relative to the project root, and env adds process environment variables. The current host requires an ownerAgentId so the task can appear in Work and completion can be correlated to an agent.

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

export async function activate(ctx: ActivateContext): Promise<void> {
  const project = await ctx.services?.workspace.getCurrentProject();
  if (!project) return;

  const task = await ctx.services?.tasks.runCommand({
    projectId: project.id,
    ownerAgentId: "00000000-0000-0000-0000-000000000000",
    label: "Check npm",
    command: "npm",
    args: ["--version"],
    cwd: ".",
    env: { CI: "1" },
    recordOnly: true
  });

  const status = await ctx.services?.tasks.getCommandStatus(task.taskId);
  ctx.logger.info("command task", {
    taskId: task.taskId,
    state: status?.state,
    exitCode: status?.exitCode
  });
}

list, getStatus, attachOutput, cancel and retry continue to operate on tasks visible through IdeA's Work read model. getCommandStatus reads a launched command task directly from the host task store.

Toolchain Diagnostics

Use ctx.services.tooling.diagnose() to check external prerequisites without hard-coding one stack into the SDK. A request can probe executables, inspect environment variables and validate workspace files in one structured result.

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

export async function activate(ctx: ActivateContext): Promise<void> {
  const diagnostic = await ctx.services?.tooling.diagnose({
    tools: [
      {
        id: "node",
        executable: "node",
        versionArgs: ["--version"],
        required: true
      }
    ],
    env: [{ name: "PATH", required: true }],
    files: [{ path: "package.json", kind: "file" }]
  });

  const node = diagnostic?.tools.find((tool) => tool.id === "node");
  ctx.logger.info("tooling diagnostic", {
    ok: diagnostic?.ok,
    nodePresent: node?.present,
    nodeVersion: node?.version,
    messages: diagnostic?.messages
  });
}

The diagnostic API is intentionally generic: it does not install tools, does not model Android devices or emulators, and does not expose language-specific ASTs.

Events And Watch

Use ctx.services.events.subscribe() for stable public host/project events. The runtime hides the host polling details and returns a disposable subscription.

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

export async function activate(ctx: ActivateContext): Promise<void> {
  const subscription = await ctx.services?.events.subscribe(
    {
      eventTypes: ["backgroundTaskChanged"],
      capacity: 100,
      onDropped: (count) => ctx.logger.warn("plugin events dropped", { count })
    },
    (event) => {
      if (event.type === "backgroundTaskChanged") {
        ctx.logger.info("task changed", {
          taskId: event.taskId,
          state: event.state
        });
      }
    }
  );

  if (subscription) ctx.subscriptions.push(subscription);

  const watch = await ctx.services?.workspace.watch("src", (event) => {
    ctx.logger.info("workspace changed", {
      path: event.path,
      kind: event.kind,
      operation: event.operation
    });
  });

  if (watch) ctx.subscriptions.push(watch);
}

Public event retention is bestEffortBounded: events are retained per subscription up to the requested/host-capped capacity, drained oldest-first, and onDropped reports when older retained events were overwritten.

Structured Config Documents

Use ctx.services.config when a plugin needs to read or update a structured project-owned configuration file without reimplementing parsing and serialization. Do not use project config documents as the default persistence mechanism for plugin-internal state; use ctx.storage for that.

First-lot format support is deliberately narrow:

• json only;
• inferred from .json when format is omitted;
• serialized as pretty JSON with a trailing newline;
• update modes: mergePatch and replace;
• mergePatch follows JSON merge-patch semantics: object keys are merged recursively and null removes a key.

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

export async function activate(ctx: ActivateContext): Promise<void> {
  const config = await ctx.services?.config.readDocument({
    path: "tooling.config.json"
  });

  await ctx.services?.config.updateDocument({
    path: "tooling.config.json",
    mode: "mergePatch",
    value: {
      enabled: true,
      lastReadFormat: config?.format ?? "json"
    }
  });
}

YAML, TOML, XML, .properties and stack-specific config models are not part of this first 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.