u

docs/api/README.md

@@ -230,6 +230,7 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
 | [`routes/vfs/upload.md`](routes/vfs/upload.md) | `POST /vfs/upload` |
 | [`routes/vfs/delete.md`](routes/vfs/delete.md) | `DELETE /vfs/{*path}` |
 | [`routes/vfs/_*path.md`](routes/vfs/_*path.md) | `GET /vfs/{*path}` |
+| [`routes/vfs/exec.md`](routes/vfs/exec.md) | `POST /vfs/{*path}` |
 | [`routes/vfs/write.md`](routes/vfs/write.md) | `PUT /vfs/{*path}` |
 | [`routes/warehouse/list.md`](routes/warehouse/list.md) | `GET /warehouse` |
 | [`routes/warehouse/create.md`](routes/warehouse/create.md) | `POST /warehouse` |
@@ -259,7 +260,7 @@ Clients subscribe via [`GET /events`](routes/events.md) (`text/event-stream`). A
 | `printer` | `POST /printer`, `PUT /printer/order`, `DELETE /printer/{id}`, `PATCH /printer/{id}`, `PUT /printer/{id}` |
 | `propertyname` | `POST /propertyname`, `PUT /propertyname/order`, `DELETE /propertyname/{id}`, `PATCH /propertyname/{id}` |
 | `stock` | `POST /stock/adjust` |
-| `vfs` | `POST /vfs/mkdir`, `POST /vfs/rename`, `POST /vfs/upload`, `DELETE /vfs/{*path}`, `PUT /vfs/{*path}` |
+| `vfs` | `POST /vfs/mkdir`, `POST /vfs/rename`, `POST /vfs/upload`, `DELETE /vfs/{*path}`, `POST /vfs/{*path}`, `PUT /vfs/{*path}` |
 | `warehouse` | `POST /warehouse`, `PUT /warehouse/order`, `DELETE /warehouse/{id}`, `PUT /warehouse/{id}` |
 
 ## DESIGN

docs/api/routes-all.md

@@ -1,6 +1,6 @@
 # Dash API Routes Overview (All)
 
-Overview of all 206 API endpoints across all modules.
+Overview of all 207 API endpoints across all modules.
 
 ### Notation
 
@@ -682,6 +682,9 @@ _none_
 #### Get a virtual filesystem file — `GET /vfs/{*path}`
 - Params: `path: str, query: download?: bool, raw?: bool`
 - Returns: `200 str`
+#### Execute a virtual filesystem applet — `POST /vfs/{*path}`
+- Params: `path: str, body?: { input?: {}, timeout?: int, max_output?: int }`
+- Returns: `200 { ok: bool, result: any|null, stdout: str, consoleLines: int, durationMs: int, truncated?: bool, truncationNote?: str }`
 #### Create or overwrite a virtual filesystem file — `PUT /vfs/{*path}`
 - Params: `path: str, body: { content: str, mime?: str }`
 - Returns: `200 { success: bool, file: { name: str, size: int, mime: str, updated_at: str } }`

docs/api/routes/vfs/exec.md

@@ -0,0 +1,77 @@
+# `POST /vfs/{*path}`
+
+Protected. Requires a valid session cookie (`credentials: 'include'`).
+
+Execute a virtual filesystem applet
+
+Runs a `.applet.js` file from the virtual filesystem for the authenticated user's selected company
+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.
+
+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
+not end in `.applet.js`. Read-only database paths are rejected with HTTP 403.
+
+
+## Path parameters
+
+| Param | Required | Type | Description |
+|-------|----------|------|-------------|
+| `path` | yes | string | VFS-relative path to the applet file (e.g. `demo.applet.js`, `apps/report.applet.js`) |
+
+## Body (JSON) — _optional_
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `input` | no | object | Input values passed to the exported applet function as `applet_input`. Defaults to an empty object. |
+| `timeout` | no | integer | Execution timeout in milliseconds, clamped to 1000…60000. Default 20000. |
+| `max_output` | no | integer | Maximum stdout characters before truncation. Default 20000. |
+
+```json
+{
+  "input": {},
+  "timeout": 1,
+  "max_output": 1
+}
+```
+
+## Signals
+
+On success, emits SSE signal: `vfs` (see [`GET /events`](../events.md)).
+
+## Response `200`
+
+Applet executed successfully
+
+```json
+{
+  "ok": true,
+  "result": null,
+  "stdout": "…",
+  "consoleLines": 1,
+  "durationMs": 1,
+  "truncated": true,
+  "truncationNote": "…"
+}
+```
+
+## Errors
+
+| Status | Description |
+|--------|-------------|
+| 400 | No company selected, invalid path, not a .applet.js file, invalid input, or invalid applet metadata — `{"error":"…"}` |
+| 401 | Unauthorized — `{"error":"…"}` |
+| 403 | Not authorized, or cannot execute read-only database paths — `{"error":"…"}` |
+| 404 | Applet not found — `{"error":"…"}` |
+| 500 | The applet threw during execution — `{"error":"…"}` |
+| 504 | The applet exceeded the execution timeout and was terminated — `{"error":"…"}` |
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._