Blomios
033e9a86d5
- capability manifeste tooling supportée backend + transport runtime catalog - ctx.services publique côté SDK/runtime, gated par tooling - surface honnête: workspace, terminal, et tasks en observation/contrôle uniquement - docs/exemple/tests mis à jour - QA PASS sur feature/sdk-plugin-tooling-build-debug-surface
122 lines
3.0 KiB
Markdown
122 lines
3.0 KiB
Markdown
# 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.
|