u

docs/api/routes/vfs/exec.md

@@ -9,10 +9,17 @@ and returns the exported function's result.
 
 The applet file must begin with two metadata lines:
 `// @applet-input-schema {JSON Schema}` followed by
-`// @applet-output-schema {JSON Schema}`. The file exports a function that receives the posted `input`
-as `applet_input`, and execution runs in the same isolated worker sandbox as the `javascript_execute`
-tool — including authenticated `fetch()` against this API, `fs`/`vfs`, `sharp`, ExcelJS, PDFKit and
-WebCrypto globals.
+`// @applet-output-schema {name:type;name:type}`. The input schema describes the GUI form posted as
+`input`. The output line declares the RESULT COLUMNS as typed CSV — `name:type` pairs separated by `;`
+(e.g. `id:integer;name:string;active:boolean`); allowed types are `string`, `integer`, `number`,
+`boolean` and `date`. The applet exports a function that receives the posted `input` as `applet_input`
+and returns a row object (or an array of row objects) keyed by those columns.
+
+Applets return typed CSV, not JSON: `result` is a `;`-separated CSV string with a header row, and the
+response also carries `columns` (name/type) and `rows` (data row count). Only declared columns are
+emitted, in header order; missing values become empty cells. Execution runs in the same isolated worker
+sandbox as the `javascript_execute` tool — including authenticated `fetch()` against this API,
+`fs`/`vfs`, `sharp`, ExcelJS, PDFKit and WebCrypto globals.
 
 The path is taken from the URL (like `DELETE /vfs/{*path}`); the run arguments are the JSON body.
 Path traversal (`..`), null bytes, and backslashes are rejected with HTTP 400, as is a path that does
@@ -52,7 +59,17 @@ Applet executed successfully
 ```json
 {
   "ok": true,
-  "result": null,
+  "result": "id;name\n1;Kaffee",
+  "columns": [
+    {
+      "name": "…",
+      "type": "string"
+    }
+  ],
+  "rows": 1,
+  "warnings": [
+    "…"
+  ],
   "stdout": "…",
   "consoleLines": 1,
   "durationMs": 1,