feat(sdk,plugins): API publique d'accès fichiers/workspace + analyse structure (#124,#129)

2026-08-02 13:34:54 +02:00
parent 033e9a86d5
commit dce61ae1aa
27 changed files with 5895 additions and 94 deletions
--- a/sdk/IdeaSDK/src/index.ts
+++ b/sdk/IdeaSDK/src/index.ts
@ -14,22 +14,72 @@ export {
 } from "./manifest.js";
 export type {
  ActivateContext,
+  BackgroundTaskChangedEvent,
  CommandDisposable,
  CommandHandler,
  CommandRegistry,
+  CommandTaskStatus,
+  ConfigDocument,
+  ConfigDocumentFormat,
+  ConfigDocumentReadOptions,
+  ConfigDocumentService,
+  ConfigDocumentUpdateOptions,
+  ConfigDocumentWriteResult,
+  ConfigUpdateMode,
+  DiagnosticMessage,
+  EnvDiagnostic,
+  EnvRequirement,
+  EventHandler,
+  EventService,
+  EventSubscribeOptions,
+  EventSubscription,
+  FileDiagnostic,
+  FileRequirement,
  BackgroundTaskOutputAttachment,
  BackgroundTaskRetryResult,
  BackgroundTaskService,
  BackgroundTaskStatus,
  IdeAPluginModule,
+  JsonValue,
+  LayoutRegistry,
  PluginLogger,
+  PluginLayoutAvailability,
+  PluginLayoutComponent,
+  PluginLayoutDefinition,
+  PluginLayoutProps,
+  PluginLayoutRenderResult,
+  PluginLayoutState,
  PluginServices,
  PluginStorage,
+  ProjectConvention,
+  ProjectModule,
+  ProjectStructure,
+  ProjectStructureEntry,
+  ProjectStructureEntryKind,
+  PublicEvent,
+  PublicEventType,
+  RunCommandTaskOptions,
  TerminalOpenOptions,
  TerminalReattachOptions,
  TerminalReattachResult,
  TerminalService,
  TerminalSession,
+  ToolchainDiagnostic,
+  ToolchainDiagnosticRequest,
+  ToolDiagnostic,
+  ToolingService,
+  ToolRequirement,
+  WorkspaceBinaryFile,
+  WorkspaceDirEntry,
+  WorkspaceDirectoryListing,
+  WorkspaceFileChangedEvent,
  WorkspaceProject,
-  WorkspaceService
+  WorkspaceResolvedPath,
+  WorkspaceService,
+  WorkspaceStat,
+  WorkspaceStructureQuery,
+  WorkspaceTextFile,
+  WorkspaceWatch,
+  WorkspaceWatchEvent,
+  WorkspaceWatchHandler
 } from "./runtime.js";
--- a/sdk/IdeaSDK/src/runtime.ts
+++ b/sdk/IdeaSDK/src/runtime.ts
@ -3,6 +3,7 @@ export interface ActivateContext {
  logger: PluginLogger;
  subscriptions: CommandDisposable[];
  commands?: CommandRegistry;
+  layouts?: LayoutRegistry;
  storage?: PluginStorage;
  /**
   * Stable public service facade for plugins that need workspace, background
@ -40,9 +41,47 @@ export interface PluginStorage {
  delete(key: string): Promise<void>;
 }

+export type PluginLayoutState = JsonValue | undefined;
+export type PluginLayoutAvailability = "available";
+export type PluginLayoutRenderResult = unknown;
+
+export interface PluginLayoutProps<TState extends PluginLayoutState = PluginLayoutState> {
+  /** Project currently hosting this layout cell. */
+  projectId: string;
+  /** Stable layout node id for this cell instance. */
+  nodeId: string;
+  /** Layout contribution type declared in `idea-plugin.json`. */
+  layoutType: string;
+  /** Opaque JSON-serializable state persisted by the host for this cell. */
+  state: TState;
+  /** Replaces the opaque state for this cell. Values must be JSON-serializable. */
+  setState(next: TState): void;
+  /** Present layouts are only mounted when available; fallback UI is host-owned. */
+  availability: PluginLayoutAvailability;
+}
+
+export type PluginLayoutComponent<TState extends PluginLayoutState = PluginLayoutState> = (
+  props: PluginLayoutProps<TState>,
+) => PluginLayoutRenderResult;
+
+export interface PluginLayoutDefinition<TState extends PluginLayoutState = PluginLayoutState> {
+  /** Must match a layout `type` declared in this plugin's manifest. */
+  type: string;
+  component: PluginLayoutComponent<TState>;
+}
+
+export interface LayoutRegistry {
+  register<TState extends PluginLayoutState = PluginLayoutState>(
+    definition: PluginLayoutDefinition<TState>,
+  ): CommandDisposable;
+}
+
 export interface PluginServices {
  workspace: WorkspaceService;
  tasks: BackgroundTaskService;
+  tooling: ToolingService;
+  events: EventService;
+  config: ConfigDocumentService;
  terminal: TerminalService;
 }

@ -61,6 +100,117 @@ export interface WorkspaceService {
  readProjectContext(projectId?: string): Promise<string>;
  /** Updates IdeA's shared project context for the given or current project. */
  updateProjectContext(content: string, projectId?: string): Promise<void>;
+  /**
+   * Resolves and normalizes a plugin-visible path under the project root.
+   * Rejects absolute paths, `..`, empty segments and other paths the host
+   * considers outside the workspace sandbox.
+   */
+  resolvePath(path: string, projectId?: string): Promise<WorkspaceResolvedPath>;
+  /** Reads a UTF-8 text file under the project root. */
+  readTextFile(path: string, projectId?: string): Promise<WorkspaceTextFile>;
+  /** Reads raw bytes from a file under the project root. */
+  readBinaryFile(path: string, projectId?: string): Promise<WorkspaceBinaryFile>;
+  /** Writes UTF-8 text under the project root using the host's controlled write path. */
+  writeTextFile(path: string, content: string, projectId?: string): Promise<void>;
+  /** Writes raw bytes under the project root using the host's controlled write path. */
+  writeBinaryFile(path: string, bytes: Uint8Array, projectId?: string): Promise<void>;
+  /** Lists one directory under the project root. Defaults to the workspace root. */
+  listDirectory(path?: string, projectId?: string): Promise<WorkspaceDirectoryListing>;
+  /**
+   * Returns basic metadata. Missing paths resolve to `{ exists: false }`; invalid
+   * paths and permission errors reject.
+   */
+  stat(path: string, projectId?: string): Promise<WorkspaceStat>;
+  /**
+   * Extension point for host file watching. The MVP SDK reserves the public
+   * shape; hosts may reject with a clear not-implemented error until #127 lands.
+   */
+  watch(path: string, handler: WorkspaceWatchHandler, projectId?: string): Promise<WorkspaceWatch>;
+  /** Queries a bounded, generic project structure read model. */
+  queryStructure(query?: WorkspaceStructureQuery): Promise<ProjectStructure>;
+}
+
+export interface WorkspaceResolvedPath {
+  projectId: string;
+  root: string;
+  path: string;
+}
+
+export interface WorkspaceTextFile {
+  path: string;
+  content: string;
+}
+
+export interface WorkspaceBinaryFile {
+  path: string;
+  bytes: Uint8Array;
+}
+
+export interface WorkspaceDirEntry {
+  name: string;
+  path: string;
+  isDir: boolean;
+}
+
+export interface WorkspaceDirectoryListing {
+  path: string;
+  entries: WorkspaceDirEntry[];
+}
+
+export interface WorkspaceStat {
+  path: string;
+  exists: boolean;
+  isFile: boolean;
+  isDir: boolean;
+  len: number | null;
+}
+
+export interface WorkspaceWatchEvent {
+  path: string;
+  kind: "created" | "modified" | "deleted" | "renamed" | "unknown";
+  operation: string;
+  projectId: string;
+}
+
+export type WorkspaceWatchHandler = (event: WorkspaceWatchEvent) => void;
+
+export interface WorkspaceWatch {
+  dispose(): void;
+}
+
+export interface WorkspaceStructureQuery {
+  projectId?: string;
+  path?: string;
+  maxDepth?: number;
+  maxEntries?: number;
+}
+
+export type ProjectStructureEntryKind = "file" | "directory";
+
+export interface ProjectStructureEntry {
+  path: string;
+  name: string;
+  kind: ProjectStructureEntryKind;
+}
+
+export interface ProjectConvention {
+  id: string;
+  markerPath: string;
+}
+
+export interface ProjectModule {
+  path: string;
+  markerPath: string;
+  conventionId: string;
+}
+
+export interface ProjectStructure {
+  projectId: string;
+  rootPath: string;
+  entries: ProjectStructureEntry[];
+  conventions: ProjectConvention[];
+  modules: ProjectModule[];
+  truncated: boolean;
 }

 export interface BackgroundTaskStatus {
@ -88,7 +238,247 @@ export interface BackgroundTaskRetryResult {
  taskId?: string;
 }

+export interface RunCommandTaskOptions {
+  /** Project that owns the command workspace. Defaults to the focused project. */
+  projectId?: string;
+  /** Agent id used by IdeA Work for ownership, cancellation and completion delivery. */
+  ownerAgentId: string;
+  /** Human-facing label shown in Work. Defaults to the command line. */
+  label?: string;
+  /** Executable to run. Arguments are passed separately, without shell parsing. */
+  command: string;
+  /** Arguments passed to the executable. */
+  args?: string[];
+  /** Relative working directory under the project root. Defaults to the root. */
+  cwd?: string;
+  /** Extra environment variables for the command. */
+  env?: Record<string, string> | Array<[string, string]>;
+  /** When true, completion is recorded without waking the owner agent. */
+  recordOnly?: boolean;
+  /** Optional absolute deadline, epoch milliseconds. */
+  deadlineMs?: number;
+}
+
+export interface CommandTaskStatus {
+  taskId: string;
+  ownerAgentId: string;
+  projectId: string;
+  kind: string;
+  state: "queued" | "running" | "waiting" | "completed" | "failed" | "cancelled" | "expired";
+  exitCode: number | null;
+  summary: string | null;
+  stdoutTail: string | null;
+  stderrTail: string | null;
+  createdAtMs: number;
+  updatedAtMs: number;
+}
+
+export interface ToolRequirement {
+  /** Stable id chosen by the plugin for this executable prerequisite. */
+  id: string;
+  /** Executable name or path to probe. */
+  executable: string;
+  /** Version/diagnostic arguments. Defaults host-side to `--version`. */
+  versionArgs?: string[];
+  /** Whether this tool must pass for the whole diagnostic to be ok. */
+  required?: boolean;
+  /** Extra environment variables for this probe. */
+  env?: Record<string, string> | Array<[string, string]>;
+}
+
+export interface EnvRequirement {
+  /** Environment variable name. */
+  name: string;
+  /** Whether the variable must be present and match. */
+  required?: boolean;
+  /** Optional exact expected value. */
+  equals?: string;
+}
+
+export interface FileRequirement {
+  /** Relative workspace path. */
+  path: string;
+  /** Whether the path must exist and match `kind`. */
+  required?: boolean;
+  /** Expected workspace path kind. */
+  kind?: "file" | "directory" | "any";
+}
+
+export interface ToolchainDiagnosticRequest {
+  /** Project to inspect. Defaults to the focused project. */
+  projectId?: string;
+  /** Relative working directory under the project root. Defaults to the root. */
+  cwd?: string;
+  /** Executable probes to run. */
+  tools?: ToolRequirement[];
+  /** Environment variable prerequisites to inspect. */
+  env?: EnvRequirement[];
+  /** Workspace file prerequisites to validate. */
+  files?: FileRequirement[];
+}
+
+export interface ToolchainDiagnostic {
+  projectId: string;
+  cwd: string;
+  ok: boolean;
+  tools: ToolDiagnostic[];
+  env: EnvDiagnostic[];
+  files: FileDiagnostic[];
+  messages: DiagnosticMessage[];
+}
+
+export interface ToolDiagnostic {
+  id: string;
+  executable: string;
+  present: boolean;
+  ok: boolean;
+  status: "ok" | "failed" | "missing";
+  required: boolean;
+  exitCode: number | null;
+  version: string | null;
+  stdout: string | null;
+  stderr: string | null;
+  error: string | null;
+}
+
+export interface EnvDiagnostic {
+  name: string;
+  present: boolean;
+  ok: boolean;
+  required: boolean;
+  value: string | null;
+  status: "ok" | "missing" | "mismatch";
+}
+
+export interface FileDiagnostic {
+  path: string;
+  exists: boolean;
+  ok: boolean;
+  required: boolean;
+  kind: "file" | "directory" | "other" | "missing";
+  expectedKind: "file" | "directory" | "any" | null;
+  len: number | null;
+}
+
+export interface DiagnosticMessage {
+  level: "info" | "warning" | "error";
+  message: string;
+}
+
+export interface ToolingService {
+  /** Runs generic external-toolchain diagnostics for executables, env and files. */
+  diagnose(request: ToolchainDiagnosticRequest): Promise<ToolchainDiagnostic>;
+}
+
+export type PublicEventType = "workspaceFileChanged" | "backgroundTaskChanged";
+
+export type PublicEvent = WorkspaceFileChangedEvent | BackgroundTaskChangedEvent;
+
+export interface WorkspaceFileChangedEvent {
+  type: "workspaceFileChanged";
+  sequence: number;
+  occurredAtMs: number;
+  projectId: string;
+  path: string;
+  operation: string;
+}
+
+export interface BackgroundTaskChangedEvent {
+  type: "backgroundTaskChanged";
+  sequence: number;
+  occurredAtMs: number;
+  projectId: string;
+  taskId: string;
+  ownerAgentId: string;
+  state: string;
+}
+
+export interface EventSubscribeOptions {
+  /** Project to observe. Defaults to the focused project. */
+  projectId?: string;
+  /** Public event types to retain. Empty/omitted means every supported event. */
+  eventTypes?: PublicEventType[];
+  /** Per-subscription retained capacity. Host clamps to its supported bounds. */
+  capacity?: number;
+  /** Polling cadence used by the runtime facade. Defaults to 1000 ms. */
+  pollIntervalMs?: number;
+  /** Maximum events drained per poll. Host clamps to its supported bounds. */
+  maxEventsPerPoll?: number;
+  /** Called when the host reports dropped retained events for this subscription. */
+  onDropped?: (count: number) => void;
+}
+
+export interface EventSubscription {
+  readonly subscriptionId: string;
+  readonly projectId: string;
+  readonly eventTypes: PublicEventType[];
+  readonly retention: string;
+  dispose(): void;
+}
+
+export type EventHandler = (event: PublicEvent) => void;
+
+export interface EventService {
+  /** Subscribes to stable, best-effort bounded public host/project events. */
+  subscribe(options: EventSubscribeOptions, handler: EventHandler): Promise<EventSubscription>;
+}
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type ConfigDocumentFormat = "json";
+export type ConfigUpdateMode = "mergePatch" | "replace";
+
+export interface ConfigDocumentReadOptions {
+  /** Project that owns the config document. Defaults to the focused project. */
+  projectId?: string;
+  /** Relative path under the project root. */
+  path: string;
+  /** Explicit format. Omit to infer from extension. First lot supports only `json`. */
+  format?: ConfigDocumentFormat;
+}
+
+export interface ConfigDocumentUpdateOptions extends ConfigDocumentReadOptions {
+  /** Update mode. Defaults host-side to `mergePatch`. */
+  mode?: ConfigUpdateMode;
+  /** Replacement value or JSON merge patch. */
+  value: JsonValue;
+}
+
+export interface ConfigDocument<T extends JsonValue = JsonValue> {
+  projectId: string;
+  path: string;
+  format: ConfigDocumentFormat;
+  value: T;
+}
+
+export interface ConfigDocumentWriteResult {
+  projectId: string;
+  path: string;
+  format: ConfigDocumentFormat;
+  mode: ConfigUpdateMode;
+  bytesWritten: number;
+}
+
+export interface ConfigDocumentService {
+  /** Reads and parses a structured config document. First lot supports JSON only. */
+  readDocument<T extends JsonValue = JsonValue>(
+    options: ConfigDocumentReadOptions,
+  ): Promise<ConfigDocument<T>>;
+  /** Writes a full replacement or JSON merge patch. First lot supports JSON only. */
+  updateDocument(options: ConfigDocumentUpdateOptions): Promise<ConfigDocumentWriteResult>;
+}
+
 export interface BackgroundTaskService {
+  /** Launches a non-interactive command as a first-class IdeA background task. */
+  runCommand(options: RunCommandTaskOptions): Promise<CommandTaskStatus>;
+  /** Reads one command task directly from the host task store. */
+  getCommandStatus(taskId: string): Promise<CommandTaskStatus | null>;
  /** Lists background tasks visible in the project work-state read model. */
  list(projectId?: string): Promise<BackgroundTaskStatus[]>;
  /** Reads one task status from the project work-state read model. */