docs(sdk): feedbacks menu host génériques — #329 ; README + docs commands-and-feedback/menus/services : failed/skipped sans message Git codé en dur ni payload brut, opened/alreadyOpen succès silencieux, logs host pluginId/commandId/status/reason/message, vue de diagnostic reste accessible quand Git/ADB/Gradle ou autre outil optionnel manque, workspace.execTool rappelé ; QA verte : npm run check, git diff --check

docs/commands-and-feedback.md

@@ -1,7 +1,7 @@
 # Commands And Feedback
 
-This document is the normative SDK contract for plugin commands that may launch
-background work.
+This document is the normative SDK contract for plugin commands, including
+commands that open a view or launch background work.
 
 ## Contract
 
@@ -26,14 +26,16 @@ manifest contribution -> command id -> registered command handler -> optional ta
 - Feedback objects must be stable enough for agents and programmatic callers to
   parse, and their messages must be readable by humans.
 - The human menu-click UI presents minimal host-owned feedback for `skipped`
-  and `failed` results. It intentionally does not expose the raw result payload.
+  and `failed` results. It intentionally does not expose the raw result payload
+  or assume which tool (Git, ADB, Gradle, and so on) the plugin uses.
   For successful actions and richer status, open or focus a plugin layout/window
   from the handler with
   `ctx.services.windows.open({ layoutType, state })`.
 
 ## Preconditions
 
-Check preconditions before calling `runCommand()`:
+Check preconditions before calling `runCommand()`. These are task-launch
+preconditions, not prerequisites for opening an explanatory view:
 
 - `ctx.services` exists. Plugins need the `ui` or `tooling` capability for the
   service facade.
@@ -50,6 +52,12 @@ Check preconditions before calling `runCommand()`:
 - Do not use `ctx.pluginRoot` as `cwd`; `cwd` remains relative to the project root.
 - `command` and `args` are separate values. Do not shell-join user input.
 
+A command whose purpose is to open or focus a diagnostic/configuration view
+should call `services.windows.open(...)` before probing optional executables.
+Missing Git, ADB, Gradle, or another tool must not block that view when the view
+can explain the degraded state and the next step. Probe tools from the view (or
+from its data loader) and render the degraded state there.
+
 If any required precondition fails, return a skipped result:
 
 ```ts
@@ -67,21 +75,30 @@ with equivalent fields:
 
 ```ts
 type CommandFeedback =
+  | { status: "opened"; message?: string; alreadyOpen: boolean }
   | { status: "skipped"; reason: string; message: string }
+  | { status: "failed"; reason?: string; message?: string }
   | { status: "launched"; taskId: string; state: string; message: string };
 ```
 
 Use the same `status` vocabulary consistently:
 
+- `opened`: the requested view was opened or focused. `alreadyOpen: true` is a
+  successful focus operation, not a failure or skip.
 - `skipped`: no background task was created.
 - `launched`: a task was created; inspect the task state for later progress.
-- `failed`: the handler itself failed before it could return normally.
+- `failed`: the handler caught a failure and returned structured failure
+  feedback. An uncaught/rejected handler is also treated as a failure by the
+  host.
 
 Visible surfaces are intentionally distinct:
 
 - Command return value: immediate feedback for programmatic callers and agents.
   The human menu host maps `skipped` and `failed` results to concise feedback;
-  plugin-specific fields and messages are not displayed verbatim.
+  plugin-specific fields and messages are not displayed verbatim. `opened`
+  results, including `alreadyOpen: true`, succeed without an alert. The host
+  logs structured diagnostics with `pluginId`, `commandId`, `status`, `reason`
+  and `message`; raw objects, stack traces and internal ids are not user-facing.
 - Plugin layout/window: the normative visible feedback surface for menu actions
   that need to show status, results or next steps to a human. The layout must be
   declared in `idea-plugin.json` and registered during activation.
@@ -146,6 +163,11 @@ const plugin: IdeAPluginModule = {
 export default plugin;
 ```
 
+The `opened` branch above must remain successful even when an optional tool
+diagnosed by `HealthView` is absent. If `windows.open(...)` itself rejects, log
+the technical cause and either let the promise reject or return `failed`; the
+host will show generic, plugin-neutral feedback rather than the raw message.
+
 Background task feedback:
 
 ```ts