mirror of
https://github.com/storytold/photocraft.git
synced 2026-10-14 11:16:53 -04:00
* Docs: document the engine.commands reply shape (#3684) engine.commands, the engine command command.list and the MCP tool command_list reply with a bare JSON array of command objects, which the docs never said. Document the shape (keys, types, an example element, how filter/enabled_only narrow it) in control-protocol.md and mcp.md, state it in the MCP tool description, and pin it with an rpc test so the docs cannot drift. The shape itself is unchanged, so existing agents and scripts keep working. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * Command list docs/test: include main's disabledReason and needsDocument keys Main added `disabledReason` and `needsDocument` to every command list row (#3664), so the documented shape and the pinning test now list all eight keys. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
This commit is contained in:
David MannandClaude Opus 5.5 authored and GitHub committed
1 parent
1460187522
commit
55ae9bc11b
4 files changed
+72
-6
No files matched your search
@@ -363,6 +363,40 @@ mod tests {
|
||||
}
|
||||
}
|
||||
|
||||
/// Pins the reply shape documented in docs/control-protocol.md › Command list replies
|
||||
/// (#3684): a bare JSON array (not `{"commands": [...]}`), one object per command with
|
||||
/// exactly these keys, from `engine.commands` (filtered or not) and `command.list`.
|
||||
#[test]
|
||||
fn command_list_replies_are_documented_array_of_objects() {
|
||||
let h = session();
|
||||
let mut g = h.lock().unwrap();
|
||||
let all = g.handle("engine.commands", json!({})).unwrap();
|
||||
let filtered = g.handle("engine.commands", json!({"filter": "BLUR"})).unwrap();
|
||||
let engine = g.handle("engine.execute", json!({"command": "command.list"})).unwrap();
|
||||
for (name, reply) in [("engine.commands", &all), ("engine.commands {filter}", &filtered), ("command.list", &engine)] {
|
||||
let items = reply.as_array().unwrap_or_else(|| panic!("{name} must reply with a bare array, got {reply}"));
|
||||
assert!(!items.is_empty(), "{name}");
|
||||
for c in items {
|
||||
let mut keys: Vec<&str> = c.as_object().unwrap().keys().map(String::as_str).collect();
|
||||
keys.sort_unstable();
|
||||
assert_eq!(keys, ["disabledReason", "enabled", "id", "label", "menu", "needsDocument", "params", "shortcut"], "{name}: {c}");
|
||||
assert!(c["id"].is_string() && c["label"].is_string() && c["params"].is_string() && c["enabled"].is_boolean(), "{c}");
|
||||
assert!(c["needsDocument"].is_boolean(), "{c}");
|
||||
assert_eq!(c["disabledReason"].is_null(), c["enabled"] == true, "disabledReason is null exactly when enabled: {c}");
|
||||
assert!(c["menu"].as_array().unwrap().iter().all(Value::is_string), "{c}");
|
||||
assert!(c["shortcut"].is_string() || c["shortcut"].is_null(), "{c}");
|
||||
}
|
||||
}
|
||||
let n_all = all.as_array().unwrap().len();
|
||||
assert_eq!(engine.as_array().unwrap().len(), n_all);
|
||||
let filtered = filtered.as_array().unwrap();
|
||||
assert!(filtered.len() < n_all);
|
||||
assert!(filtered.iter().all(|c| format!("{} {}", c["id"], c["label"]).to_lowercase().contains("blur")));
|
||||
let new = all.as_array().unwrap().iter().find(|c| c["id"] == "file.new").unwrap();
|
||||
assert_eq!((&new["menu"], &new["shortcut"], &new["enabled"]), (&json!(["File"]), &json!("Cmd+N"), &json!(true)), "{new}");
|
||||
assert_eq!((&new["disabledReason"], &new["needsDocument"]), (&Value::Null, &json!(false)), "{new}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lines_round_trip_and_errors() {
|
||||
let h = session();
|
||||
|
||||
@@ -796,7 +796,8 @@ impl PhotocraftMcp {
|
||||
}
|
||||
}
|
||||
|
||||
#[tool(description = "List engine commands: id, label, menu path, shortcut, parameter doc, enabled now. \
|
||||
#[tool(description = "List engine commands. Returns a JSON array (no wrapper object) of {id, label, menu: [path], \
|
||||
shortcut: string|null, params: doc string, enabled: bool, disabledReason: string|null, needsDocument: bool}. \
|
||||
`disabledReason` says why a command is off (null when enabled); `needsDocument` is true when it is off because no \
|
||||
document is open: create or open one first (doc_new, doc_open).")]
|
||||
async fn command_list(&self, Parameters(p): Parameters<ListParams>) -> Result<CallToolResult, McpError> {
|
||||
|
||||
@@ -45,7 +45,7 @@ The transport is `apps/photocraft/src/control_server.rs`, and the handlers are i
|
||||
## Methods
|
||||
|
||||
- `engine.execute {command, params}`: run any engine or UI command by id. Engine commands run directly with their default params and never open a dialog. Use `ui.menu.invoke` for menu-click behaviour, which opens a command's dialog when no params are given. `params` must be a JSON object (omit it or pass `null` for none); an array, string, number or boolean is an error naming the command, in every transport (control channel, `serve`, MCP and the CLI)
|
||||
- `engine.commands`: list commands with enablement
|
||||
- `engine.commands`: list commands with enablement; the `result` is a JSON array of command objects (see [Command list replies](#command-list-replies))
|
||||
- `ui.inspect`: full UI state (tool, panels, views, dialogs, windows, window size). The menu tree is not included; use `ui.menu.list`. `brushPicker` is `null` while closed and `{pos: [x, y], size: [w, h]?, list: {collapsed, filter, renaming, showName, showStroke, showTip, scale}}` while the Brush Preset picker is open (coordinates in screen points; `size` is the picker's content size once its corner grip was dragged, `null` before that, and the drag remembers both dimensions; the three `show*` flags pick the parts of each preset's card — at least one is always on; `scale` is the footer slider, 0.15–2 with 1 the standard, multiplying the cards' width and height — the heights stop at half size and the name and tip-size text hold their 1.0 size — and dropping the tips' size numbers at 0.40 and below; the parts and the scale are remembered across restarts, while the search, collapsed groups and a rename in progress are not). `view` holds the View/Window/Type preferences: `screen_mode`, `extras`, `show` and `snap_to` flags, `flip_horizontal`, `arrange` (Window › Arrange layout), pixel aspect, font preview size, language options. `perf.timings.gpuInfo` holds the graphics adapter, backend, driver, the backend chosen at launch and why, the canvas renderer (`gpu`/`cpu`) and, after a device loss, `lost` (`help.systemInfo` returns the same as `info`)
|
||||
- `ui.set {tool?, panels?, dockTabs?, dock?, dockWidth?, colorPanel?, maskTarget?, vectorMaskTarget?, selectionMode?, zoom?, center?, rotation?, fit?, theme?, brushSize?, brushSection?, brushTab?, brushesView?, brushPicker?, brushPickerName?, brushPickerStroke?, brushPickerTip?, brushPickerScale?, gradientBlendMode?, gradientClassic?, shapeStroke?}`: change UI state; any other field is an error, checked before anything changes (`zoom` is the canvas zoom where 1 = 100%, one document pixel per physical display pixel, so a scaled display doesn't magnify the image; `theme` is `pro`, `proMedium`, `studio`, `studioLight` or `classic`; `selectionMode` is the selection tools' options-bar mode, 0 New, 1 Add, 2 Subtract, 3 Intersect; `brushSection` indexes the Brush Settings sections, `brushTab` 0 = Brush Settings, 1 = Brushes; `brushesView` is `list` or `grid` for the Brushes panel; `brushPickerName`, `brushPickerStroke` and `brushPickerTip` are the Brush Preset picker's card parts (booleans, at least one on), and `brushPickerScale` its footer card-scale slider (0.15 to 2, 1 the standard); `brushPicker` is `[x, y]` in screen points to open the Brush Preset picker there (as a right-click with a painting tool does) or `null` to close it, and picking a preset in it is `tools.setBrush {"preset": name}`; `dock` is `{order: ["layers", …], heights: {"properties": 180}, collapsed: ["color"], tabOrder: {"layers": ["Paths", "Layers", "Channels"]}}`, the right-dock groups top to bottom, their heights in points, the groups collapsed to their tab strip and each group's tab order left to right by panel name (a group left out keeps its default order, unknown names are ignored and tabs not listed follow in their default order; `dockTabs` keeps indexing tabs in their default order); `dockWidth` sets the right dock width in points, clamped to 250..520; `colorPanel` is `{background}`, whether the Color panel edits the background colour; `maskTarget` targets the active layer's mask, which, like Photoshop, swaps in the foreground/background pair kept for masks (white/black until one is picked) and swaps the pixels' pair back when the pixels are targeted again)
|
||||
- `typeTransform` is `null` outside a temporary Ctrl/Cmd Type-tool drag. During a drag it reports its source document/revision, original affine, oriented `frame` (layer, local bounds, document-space corners and pivot), and captured `gesture`. Drive it with `ui.pointer` and `command: true` at `down`; `move`/`up` may release the modifier. The document/history remain unchanged during preview, and `up` applies one `type.edit` within `textEdit`'s session. Pressing Escape during the drag cancels only the preview. This pointer state is never restored from saved UI state.
|
||||
@@ -94,7 +94,7 @@ Change the UI language without restarting with `prefs.set`:
|
||||
are documented in [UI localisation](localization.md). `prefs.get` and the existing preference
|
||||
store expose and persist the same setting; scripts keep using canonical command IDs.
|
||||
|
||||
`engine.execute` runs any command by id. `engine.commands` (or the engine command `command.list`) lists them all, with labels, menu paths, shortcuts, a parameter description, and whether each is currently enabled. Each row carries `enabled` (bool), `disabledReason` (`null` when enabled, otherwise the precondition that failed, such as `"no document open"`, `"no selection"` or `"the clipboard is empty"`) and `needsDocument` (true when the command is off because no document is open, so the first step is to create or open one; a command may still have its own precondition after that, such as an active text layer. False when enabled or off for another reason). With no document open, nearly every document command reports `enabled: false, needsDocument: true`; plan around `needsDocument` rather than reading `enabled` alone (#3664). Examples:
|
||||
`engine.execute` runs any command by id. `engine.commands` (or the engine command `command.list`) lists them all, with labels, menu paths, shortcuts, a parameter description, and whether each is currently enabled (reply shape: [Command list replies](#command-list-replies)). Each row carries `enabled` (bool), `disabledReason` (`null` when enabled, otherwise the precondition that failed, such as `"no document open"`, `"no selection"` or `"the clipboard is empty"`) and `needsDocument` (true when the command is off because no document is open, so the first step is to create or open one; a command may still have its own precondition after that, such as an active text layer. False when enabled or off for another reason). With no document open, nearly every document command reports `enabled: false, needsDocument: true`; plan around `needsDocument` rather than reading `enabled` alone (#3664). Examples:
|
||||
|
||||
| Command | Params |
|
||||
|---|---|
|
||||
@@ -174,6 +174,35 @@ their usual file access. Source replacement, relinking and export commands remai
|
||||
double-clicking its thumbnail in Layers. Text input, Commit and Cancel use the existing Type tool
|
||||
editing session; non-type layers return an error without changing the tool or document.
|
||||
|
||||
### Command list replies
|
||||
|
||||
`engine.commands` (control channel and `serve`), the engine command `command.list` and the MCP
|
||||
tool `command_list` all reply with a bare JSON array, not an object: there is no
|
||||
`{"commands": [...]}` wrapper. On the control channel and `serve` the array is the reply's
|
||||
`result` (`{"id":1,"ok":true,"result":[…]}`); the MCP tool returns it as its JSON text.
|
||||
Each element describes one command, in registry order:
|
||||
|
||||
```json
|
||||
{"id":"file.new","label":"New…","menu":["File"],"shortcut":"Cmd+N","params":"{\"width\":1..300000=1920,…}","enabled":true,"disabledReason":null,"needsDocument":false}
|
||||
```
|
||||
|
||||
| Key | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `id` | string | The id to pass to `engine.execute` / `command_run` |
|
||||
| `label` | string | Menu label |
|
||||
| `menu` | array of strings | Menu path above the item (`[]` for commands without a menu item) |
|
||||
| `shortcut` | string or `null` | Default shortcut, e.g. `"Cmd+Shift+X"` |
|
||||
| `params` | string | Human-readable parameter doc (not a JSON schema) |
|
||||
| `enabled` | boolean | Whether the command can run in the current state |
|
||||
| `disabledReason` | string or `null` | Why the command can't run now (`null` when `enabled`) |
|
||||
| `needsDocument` | boolean | `true` when it is off because no document is open (#3664) |
|
||||
|
||||
Filtering narrows the same array without changing its elements: `serve`'s `engine.commands
|
||||
{filter}` and the MCP tool's `filter` keep commands whose id or label contains the text
|
||||
(case-insensitive), and the MCP tool's `enabled_only` keeps those with `enabled: true`. The
|
||||
desktop control channel's `engine.commands` takes no filter and always returns every command.
|
||||
The shape is pinned by a test in `crates/automation/src/rpc.rs` (#3684).
|
||||
|
||||
### Background jobs (#210)
|
||||
|
||||
Long commands (every `filter.*`, `edit.contentAwareFill`, `edit.contentAwareScale`, `file.automate.photomerge`, `brush.presets.importAbr`), file opens and interactive saves (File › Save, Save As and the TIFF Options continuation, #2017) run as background jobs in the desktop app: the window keeps drawing, the status bar shows progress with a Cancel button, and jobs that lock the active document show a modal progress dialog (Esc cancels). `engine.execute`, `ui.menu.invoke`, `ui.dialog.confirm` and `app.save` still wait for the result by default; pass `"wait": false` to get `{job, pending: true}` at once, then poll `jobs.list` (`state`: running, done, failed, cancelled; `progress` 0–1; the result or error) and stop it with `jobs.cancel {job}`. A cancelled or failed job leaves the document unchanged. While a job runs, commands that would edit its document fail with "… is still running on this document". `ui.inspect` reports `jobs` (running jobs, opening files, saving files). Set `PHOTOCRAFT_INLINE_JOBS=1` to run everything inline.
|
||||
@@ -267,7 +296,7 @@ How each MCP tool maps onto control methods in bridge mode:
|
||||
|---|---|
|
||||
| `command_run {id, params, wait?}` | `engine.execute {command: id, params, wait}` |
|
||||
| `jobs_list` / `jobs_cancel {job?}` | `jobs.list` / `jobs.cancel {job?}` |
|
||||
| `command_list {filter?, enabled_only?}` | `engine.commands` (filtered by the MCP server; rows keep `disabledReason` and `needsDocument`) |
|
||||
| `command_list {filter?, enabled_only?}` | `engine.commands` (filtered by the MCP server; replies with the same bare array, rows keep `disabledReason` and `needsDocument`, see [Command list replies](#command-list-replies)) |
|
||||
| `doc_new {…}` | `engine.execute {command: "file.new", params}` |
|
||||
| `doc_inspect` | `engine.execute {command: "document.inspect"}` |
|
||||
| `doc_open {path}` | `app.open {path}` |
|
||||
@@ -325,7 +354,7 @@ no MCP framing, no app start-up per command. Configure its file access with the
|
||||
|---|---|
|
||||
| `engine.execute` | `{command, params?, wait?}`: any engine command (`wait: false` starts a long one as a background job: `{job, pending}`) |
|
||||
| `jobs.list` / `jobs.cancel` | `{}` / `{job?}`: background jobs; cancel one or all. Every request (and MCP tool call) first applies the jobs that finished, so `doc.save`, `doc.inspect`, `doc.render` and `session.list` include a finished job's result without polling `jobs.list` first |
|
||||
| `engine.commands` | `{filter?}`: registry with params docs and enablement (`enabled`, `disabledReason`, `needsDocument`) |
|
||||
| `engine.commands` | `{filter?}`: registry with params docs and enablement (`enabled`, `disabledReason`, `needsDocument`); `result` is a bare array of command objects ([Command list replies](#command-list-replies)) |
|
||||
| `session.list` | open documents and the active index |
|
||||
| `doc.open` / `doc.new` | `{path}` / `file.new` params |
|
||||
| `doc.place` | `{path, scale? (percent), fit? (true), center? ([x, y]), index?}`: places a file as a Smart Object layer above the active one and returns `{layer, scale, bounds}`. `path` resolves beneath the read root, so this is the capability-scoped `file.placeEmbedded` — that command itself still refuses an ambient path |
|
||||
|
||||
+3
-1
@@ -13,7 +13,9 @@ described in [development.md](development.md). UI tools require a running deskto
|
||||
## Tools and resources
|
||||
|
||||
- `command_list`: discover engine ids, parameter docs and current enabled state; accepts
|
||||
`filter` and `enabled_only`.
|
||||
`filter` and `enabled_only`. Returns a bare JSON array of
|
||||
`{id, label, menu, shortcut, params, enabled, disabledReason, needsDocument}` objects (see
|
||||
[Command list replies](control-protocol.md#command-list-replies)).
|
||||
- `command_run`: `id`, optional `params` and `wait`. Command parameters remain engine-defined.
|
||||
- `command_batch`: ordered `steps`, optional `stop_on_error` (default true); stops at the first
|
||||
error unless false. Not an atomic transaction: earlier successful steps stay applied, with
|
||||
|
||||
Reference in new issue
Block a user