Repository navigation
Expand file tree
/
Copy pathplugin.wit
More file actions
193 lines (191 loc) · 9.41 KB
/
Copy pathplugin.wit
File metadata and controls
193 lines (191 loc) · 9.41 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
package craft:plugin@0.2.0;
// Capabilities are sets of the interfaces in this file. A plugin names the ones it needs in its
// manifest's `capabilities` list:
// - `commands@0.2`: types, commands, log, control, files, clock and entry (world `command-plugin`);
// - `formats@0.2`: file-format slots (RFC 0015 §4). An import slot is world `importer-plugin`
// (types, log, control, clock, source, design and importer); an export slot is world
// `exporter-plugin` (types, commands, log, control, clock and formats-provider). A plugin
// declares its slots in its manifest (kind, extensions, label, options, needs_plugin_data), so
// the install review shows them before any of its code runs;
// - `evaluate@0.2`: with `formats`, evaluate, so an importer can check its result;
// - `storage@0.1`: with `commands`, the app's `storage.*` commands and the `storage` interface, so a
// plugin keeps its own data in the open design: its main document as JSON, its files as bytes.
// - `design@0.1`: with `commands`, design-state, for document identity/revision and read listeners.
// - `forms@0.1`: with `commands`, forms.open, to request a populated command form;
// programs receive an interactive-required refusal instead of a window.
// Later capabilities (ui, viewport) arrive as their own interfaces. While the version is
// 0.x, a minor version may break the one before it. 0.2 added `plugin-error.unsupported`. A host
// still runs plugins built against 0.1 (`../wit-0.1/plugin.wit`): it reads the version from the
// component's imports and exports, and shows their `invalid-input` as before.
// App commands and their schemas are data; this world never names app types.
interface types {
type json = string;
record command-failure { command: string, reason: string }
record field-failure { field: string, reason: string }
variant plugin-error {
permission-denied(string),
command-failed(command-failure),
limit-exceeded(string),
invalid-manifest(field-failure),
invalid-input(field-failure),
trap(string),
cancelled,
// The input is valid, but this plugin does not handle it: a file it can open in general
// but not this one (no solids, a newer file version, a feature it does not convert), or
// an option value it does not offer. The text says what it does not support, in the
// user's words. Use `invalid-input` for input that is broken.
unsupported(string),
}
}
// The app's command surface: the same commands, inputs and results its MCP clients get.
interface commands {
use types.{json, plugin-error};
run: func(command: string, args: json) -> result<json, plugin-error>;
}
// Additive forms@0.1 capability. Existing command components need not import this.
interface forms {
use types.{json, plugin-error};
open: func(entry: string, params: json) -> result<_, plugin-error>;
}
// Additive read-only import: JSON {document_id: string, revision: string}, or null with no document.
// Both fields are opaque printable ASCII, bounded to 128 characters; compare them for equality.
// Importing this interface requires the manifest capability design@0.1. Older components omit it.
interface design-state {
use types.{json, plugin-error};
get-token: func() -> result<json, plugin-error>;
}
interface log {
enum level { debug, info, warn, error }
log: func(level: level, message: string);
}
interface control {
progress: func(fraction: f32, message: string);
cancelled: func() -> bool;
}
interface files {
use types.{plugin-error};
read-file: func(grant: string, path: string) -> result<list<u8>, plugin-error>;
write-file: func(grant: string, path: string, data: list<u8>) -> result<_, plugin-error>;
}
interface clock {
now: func() -> u64;
}
// A plugin's own files in the open design (capability `storage@0.1`), as bytes: never as text.
// Files are named by a plain relative path; a cache file is one the plugin can make again, which
// a save may drop. Only the plugin's own run writes its files; anyone reads them.
interface storage {
use types.{plugin-error};
// Writes the running plugin's file `name` (`cache`: as a cache file), its bytes as they are;
// `append` adds them to the file's end, to write a large file in parts. One name is one file:
// writing it as the other kind moves it. Returns the file's size. Part of the run's one undo step.
put-blob: func(name: string, data: list<u8>, cache: bool, append: bool) -> result<u64, plugin-error>;
// Up to `len` bytes (at most 1 MiB) of a plugin's file from `offset`; empty past its end.
// `plugin`: whose file, the running plugin's own when left out (inside a run, only its own).
get-blob: func(plugin: option<string>, name: string, offset: u64, len: u32) -> result<list<u8>, plugin-error>;
// Up to `len` bytes (at most 1 MiB) of a plugin's main document, its saved JSON, from
// `offset`; empty past its end, or when it has none.
get-document: func(plugin: option<string>, offset: u64, len: u32) -> result<list<u8>, plugin-error>;
}
// What the plugin exports: its manifest's entries, called by name.
interface entry {
use types.{json, plugin-error};
execute: func(entry: string, params: json) -> result<json, plugin-error>;
}
// The file an importer converts, read in chunks so each host call stays small.
interface source {
use types.{plugin-error};
// The file being imported: its name, without folders, and its size in bytes.
record file-info { name: string, size: u64 }
// At most `len` bytes (up to 1 MiB) at `offset`; empty at the end of the file. `path` "" is the
// file being imported. Any other path is relative to that file's folder and needs the
// `input_folder` permission: an assembly reads its parts this way.
read: func(path: string, offset: u64, len: u32) -> result<list<u8>, plugin-error>;
// The size of a file, or none when there is no such file.
size: func(path: string) -> result<option<u64>, plugin-error>;
// The path as the folder spells it: `path` itself when it exists, else the one file whose name
// matches it ignoring case, else none. Needs `input_folder` for any path but "".
resolve: func(path: string) -> result<option<string>, plugin-error>;
}
// Where an importer writes its result: a SolidCraft design file, in order, at most 1 MiB per call.
interface design {
use types.{plugin-error};
write: func(bytes: list<u8>) -> result<_, plugin-error>;
}
// An importer checks its own result in the app (capability `evaluate@0.2`). It stages a design
// file it made; the app opens it in a private session, apart from every open design and every
// file, and runs read-only commands on it. Nothing here reaches the user's designs or files.
interface evaluate {
use types.{json, plugin-error};
// Appends at most 1 MiB to the staged design (256 MiB in all). Staging after a run starts a
// new design.
stage: func(bytes: list<u8>) -> result<_, plugin-error>;
// Runs one command on the staged design, opening it on the first run. The app names the
// commands it allows (SolidCraft: document.inspect, inspect.measure, model.edges, model.faces
// and timeline.roll_to). A command that fails returns {"error": "..."}; a design the app
// can't open fails the call.
run: func(command: string, args: json) -> result<json, plugin-error>;
// Discards the staged design and its session.
reset: func();
}
// What an importer exports: its manifest's importer entries, called by name.
interface importer {
use types.{json, plugin-error};
use source.{file-info};
// Convert `file` with the entry's declared options. The design goes to `design.write`; the
// result is the loss report: what could not be carried over, as JSON.
import-file: func(entry: string, file: file-info, options: json) -> result<json, plugin-error>;
}
// What an exporter exports: its manifest's export slots, called by name (RFC 0015 §4).
interface formats-provider {
use types.{json, plugin-error};
// Write the open design in the slot's format, with the options the user filled in the slot's
// form. The plugin reads the design through `commands`, which runs only the read-only commands
// its manifest lists. It returns the file's bytes (at most 256 MiB); the app writes them to
// the path the user chose, and only when the whole call succeeds.
export-file: func(slot: string, options: json) -> result<list<u8>, plugin-error>;
}
world command-plugin {
import forms;
import commands;
import design-state;
import log;
import control;
import files;
import clock;
import storage;
export entry;
}
world importer-plugin {
import log;
import control;
import clock;
import source;
import design;
import evaluate;
export importer;
}
world exporter-plugin {
import commands;
import log;
import control;
import clock;
export formats-provider;
}
// Optional, additive capability dialog@0.1. Existing worlds retain their exports.
interface dialog-provider {
use types.{json, plugin-error};
// Values and reply are JSON objects. The host validates the entire reply before applying it.
update-fields: func(entry: string, values: json) -> result<json, plugin-error>;
}
world dialog-plugin {
import commands;
import log;
import control;
import files;
import clock;
export dialog-provider;
}
world command-dialog-plugin {
include command-plugin;
export dialog-provider;
}