feat(sdk): ESM multi-fichiers + storage plugin-owned (#134/#139)

Documente et illustre deux contrats SDK :

- Multi-fichiers ESM : le `main` du manifeste peut importer d'autres
  fichiers du package via specifiers relatifs, servis par IdeA sur
  `idea-plugin://` (build `tsc` non bundlé). Le packager embarque tout
  `dist/**/*.js` et vérifie la présence du `main`. Les bare specifiers
  (`node_modules`) restent hors contrat : à bundler ou vendorer.
- Storage plugin-owned : `ctx.storage` est la place canonique de l'état
  interne du plugin (compteurs, flags, préférences, caches), hors des
  fichiers projet. Les APIs workspace/config restent pour le contenu
  project-owned.

L'exemple hello-plugin est éclaté en modules (constants, core/layout,
core/workspace, core/storage) pour exercer l'import relatif et le storage.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

examples/hello-plugin/src/core/layout.ts

@@ -0,0 +1,17 @@
+import type { PluginLayoutProps } from "@idea/plugin-sdk";
+
+let hasLoggedFirstLayoutRender = false;
+
+export function HelloWorldLayout(props: PluginLayoutProps): string {
+  if (!hasLoggedFirstLayoutRender) {
+    hasLoggedFirstLayoutRender = true;
+    console.info("[hello-plugin] layout first render", {
+      projectId: props.projectId,
+      nodeId: props.nodeId,
+      layoutType: props.layoutType,
+      hasState: props.state !== undefined
+    });
+  }
+
+  return "hello-world";
+}

examples/hello-plugin/src/core/storage.ts

@@ -0,0 +1,32 @@
+import type { ActivateContext } from "@idea/plugin-sdk";
+import { STORAGE_KEYS } from "../constants.js";
+
+export async function initializePluginStorage(ctx: ActivateContext): Promise<void> {
+  if (!ctx.storage) {
+    ctx.logger.warn("plugin-owned storage unavailable");
+    return;
+  }
+
+  const activationCount = await incrementStoredNumber(ctx, STORAGE_KEYS.activationCount);
+  const initialized = await ctx.storage.get<boolean>(STORAGE_KEYS.initialized);
+  if (!initialized) {
+    await ctx.storage.set(STORAGE_KEYS.initialized, true);
+  }
+
+  ctx.logger.info("plugin-owned storage ready", {
+    activationCount,
+    initialized: initialized ?? false
+  });
+}
+
+export async function recordCommandRun(ctx: ActivateContext): Promise<number | undefined> {
+  if (!ctx.storage) return undefined;
+  return incrementStoredNumber(ctx, STORAGE_KEYS.commandRunCount);
+}
+
+async function incrementStoredNumber(ctx: ActivateContext, key: string): Promise<number> {
+  const current = await ctx.storage?.get<number>(key);
+  const next = typeof current === "number" && Number.isFinite(current) ? current + 1 : 1;
+  await ctx.storage?.set(key, next);
+  return next;
+}

examples/hello-plugin/src/core/workspace.ts

@@ -0,0 +1,98 @@
+import type { ActivateContext } from "@idea/plugin-sdk";
+import { STORAGE_KEYS } from "../constants.js";
+
+export async function useWorkspaceSdk(ctx: ActivateContext): Promise<void> {
+  const workspace = ctx.services?.workspace;
+  if (!workspace) return;
+
+  const project = await workspace.getCurrentProject();
+  if (!project) {
+    ctx.logger.info("workspace service available without a focused project");
+    return;
+  }
+
+  const listing = await workspace.listDirectory(".ideai", project.id);
+  const structure = await workspace.queryStructure({
+    projectId: project.id,
+    maxDepth: 2,
+    maxEntries: 100
+  });
+
+  ctx.logger.info("workspace project inspection complete", {
+    projectId: project.id,
+    ideaiEntries: listing.entries.length,
+    conventions: structure.conventions.map((convention) => convention.id)
+  });
+
+  const diagnostic = await ctx.services?.tooling.diagnose({
+    projectId: project.id,
+    tools: [
+      {
+        id: "echo",
+        executable: "echo",
+        versionArgs: ["hello-plugin-toolcheck"],
+        required: true
+      }
+    ],
+    env: [{ name: "PATH", required: true }],
+    files: [{ path: "idea-plugin.json", kind: "file" }]
+  });
+
+  ctx.logger.info("tooling diagnostic complete", {
+    ok: diagnostic?.ok,
+    echoVersion: diagnostic?.tools.find((tool) => tool.id === "echo")?.version,
+    messages: diagnostic?.messages
+  });
+
+  const watch = await workspace.watch(".ideai", (event) => {
+    ctx.logger.info("workspace watch event", {
+      path: event.path,
+      kind: event.kind,
+      operation: event.operation
+    });
+  }, project.id);
+  ctx.subscriptions.push(watch);
+
+  const events = await ctx.services?.events.subscribe(
+    {
+      projectId: project.id,
+      eventTypes: ["backgroundTaskChanged"],
+      pollIntervalMs: 2000,
+      onDropped: (count) => ctx.logger.warn("plugin events dropped", { count })
+    },
+    (event) => {
+      if (event.type === "backgroundTaskChanged") {
+        ctx.logger.info("background task changed", {
+          taskId: event.taskId,
+          state: event.state
+        });
+      }
+    }
+  );
+  if (events) ctx.subscriptions.push(events);
+
+  const ownerAgentId = await ctx.storage?.get<string>(STORAGE_KEYS.ownerAgentId);
+  if (!ownerAgentId) {
+    ctx.logger.info("command task example skipped: no owner agent configured");
+    return;
+  }
+
+  const task = await ctx.services?.tasks.runCommand({
+    projectId: project.id,
+    ownerAgentId,
+    label: "Hello plugin command",
+    command: "echo",
+    args: ["hello from @idea/plugin-sdk"],
+    cwd: ".",
+    recordOnly: true
+  });
+
+  if (task) {
+    const status = await ctx.services?.tasks.getCommandStatus(task.taskId);
+    ctx.logger.info("command task launched", {
+      taskId: task.taskId,
+      state: status?.state ?? task.state,
+      exitCode: status?.exitCode ?? task.exitCode
+    });
+  }
+}